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Preface 


Overview  of  Document  and  Intended  Audience 

These  gui'-’  lines  describe  the  Structured  Query  Language  (SQL)  Ada  Module  Extensions,  a 
method  *  a  the  construction  of  Ada  applications  that  access  database  management  systems 
wh  '■  data  manipulation  language  is  SQL.  The  SAME  is  not  a  tool  set,  it  is  a  method  of  program 
design  and  development.  There  is  a  set  of  support  software,  called  the  SAME  standard 
packages,  which  are  needed  by  applications  using  the  SAME. 

As  its  name  implies,  the  SAME  extends  the  capabilities  of  the  Module  language  defined  in  the 
ANSI  SQL  standard  to  fit  the  needs  of  Ada.  The  defining  characteristic  of  the  use  of  the  module 
language  is  that  the  SQL  statements  appear  together,  physically  separated  from  the  Ada  appli¬ 
cation,  in  an  object  called  the  module.  The  Ada  application  accesses  the  module  through  proce¬ 
dure  calls. 

The  primary  audience  for  this  document  consists  of  application  developers  and  technicians  creat¬ 
ing  Ada  applications  for  SQL  database  management  systems.  The  document  contains  a  com¬ 
plete  description  of  the  SAME,  including  its  motivation.  It  is  not  intended  as  a  programmer's 
guide.  Organizations  using  the  SAME  may  wish  to  create  such  a  guide  from  this  document. 

The  reader  of  this  document  is  expected  to  be  familiar  with  both  Ada  and  SQL,  at  some  level  of 
detail.  An  attempt  has  been  made  to  make  the  document  accessible  to  readers  who  are  not 
experts  in  either  language.  Technical  details  are  explained  under  the  assumption  that  the  reader 
has  a  general  understanding  of  both  languages 

A  Note  on  the  Code  in  This  Document 

All  of  the  Ada  code  in  this  document  has  been  compiled,  in  many  cases  on  more  than  one 
compiler,  and  the  great  bulk  of  it  has  been  tested.  Exceptions  to  this  rule  are  noted  in  the  text. 
The  code  in  Appendix  C  has  been  exhaustively  tested  The  SQL  code  in  the  document  has  also 
been  tesfpd,  but  not  in  the  exact  form  shown.  However,  the  processes  of  transcribing  the  code 
into  the  document  and  editing  it  for  improved  readibility  may  have  inadvertently  introduced  errors. 
The  code  in  the  appendix  was  copied  into  the  document  without  modification  and  should  thus  be 
less  likely  to  contain  errors. 
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Guidelines  For  the  Use  of  the  SAME 


Abstract.  These  guidelines  describe  the  Structured  Query  Language  (SQL)  Ada 
Module  Extensions,  or  SAME,  a  method  for  the  construction  of  Ada  applications 
that  access  database  management  systems  whose  data  manipulation  language  is 
SQL.  As  its  name  implies,  the  SAME  extends  the  module  language  defined  in  the 
ANSI  SQL  standard  to  fit  the  needs  of  Ada.  The  defining  characteristic  of  the  use 
of  the  module  language  is  that  the  SQL  statements  appear  together,  physically 
separated  from  the  Ada  application,  in  an  object  called  the  module.  The  Ada  appli¬ 
cation  accesses  the  module  through  procedure  calls. 

The  primary  audience  for  this  document  consists  of  application  developers  and 
technicians  creating  Ada  applications  for  SQL  database  management  systems. 
The  document  contains  a  complete  description  of  the  SAME,  including  its  motiva¬ 
tion. 


1.  Introduction 

The  SQL  Ada  Module  Extensions  (SAME)  method  of  constructing  database  application  pro¬ 
grams  in  Ada  is  based  on  the  SQL  module  language  [2].  The  method  extends  the  features 
of  the  module  language  by  exploiting  the  capabilities  of  Ada.  This  results  in  robust  appli¬ 
cation  programs  written  in  a  style  suitable  to  Ada.  The  SAME  treats  SQL  in  much  the  same 
way  that  Ada  treats  other  foreign  languages;  that  is,  it  imports  complete  modules,  not  lan¬ 
guage  fragments. 


1 .1 .  Overview  of  the  SAME  Method 

In  the  classical  approach  to  database  access  from  application  programming  languages  [3], 
the  programmer  prepares  a  single  text  containing  statements  from  two  different  languages: 
the  programming  language  and  a  database  language.  These  two  subtexts  are  disentangled 
by  a  so-called  preprocessor,  which  outputs  the  programming  language  text  in  which  the 
database  statements  have  been  replaced  with  procedure  calls.  This  text  can  be  processed 
by  the  programming  language  compiler.  A  diagram  of  this  process  is  given  in  Figure  1-1 . 

A  programmer  using  a  modular  method  such  as  the  SAME  does  not  prepare  such  a  mixed 
text.  Instead,  he  prepares  a  compilable  Ada  program  in  which  database  services  are  ac¬ 
cessed  via  procedure  calls.  The  bodies  of  those  procedures  are  defined  by  SQL  statements 
collected  into  a  separate  text  called  a  module.  The  process  is  diagrammed  in  Figure  1  -2. 

As  Ada  database  application  programs  written  with  the  SAME  are  written  in  pure  Ada,  there 
is  no  need  for  an  Ada/SQL  preprocessor.  Ada-sensitive  editors  and  debuggers  can  be  used 
to  create  these  applications.  Since  the  database  interactions  are  written  in  standard  SQL, 
they  can  be  processed  by  existing  SQL  tools.  There  is  no  need  for  programmers  to  learn 
new  syntax  and  semantics;  no  new  system  software  need  be  written,  maintained,  and 
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Figure  1-1 :  Classical  Approach  to  Database  Access 
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Figure  1-2:  Modular  Approach  to  Database  Access 
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ported  to  process  a  new  syntax  and  semantics  for  SQL.1  In  this  regard,  the  SAME  treats 
Ada  and  SQL  as  equals.  The  SAME  interfaces  two  existing  standards  and  their  implement¬ 
ing  software.  It  does  not  attempt  to  create  an  “ideal’'  Ada  DBMS.  Rather,  it  allows  access  to 
existing,  commercial  DBMS  in  a  manner  which  exploits  the  tools  and  capabilities  of  the 
DBMS. 

Using  the  preprocessor  approach  to  database  application  programming  as  shown  in  Figure 
1-1,  the  application  programmer  must  know  the  syntax  and  semantics  of  not  only  the  pro¬ 
gramming  language  but  also  the  database  language.  These  are  rarely  identical  or  even 
similar;  certainly  not  in  the  case  of  Ada  and  SQL.  The  programmer  must  think  in  two  differ¬ 
ent  ways  as  he  alternates  between  Ada  and  SQL.  In  such  non-modular  approaches,  the 
application  programmer  must  understand  not  only  the  logic  of  the  application,  but  also  the 
logical  design  of  the  stored  database.  He  must  know  not  only  what  information  services  the 
application  program  requires  of  the  database,  but  also  how  the  database  can  be  made  to 
provide  those  services. 

Modular  approaches,  such  as  the  SAME,  make  it  possible  for  the  application  and  database 
programming  tasks  to  be  assigned  to  different  programmers.  For  development  organizations 
which  are  large  enough  to  afford  this  specialization  of  roles,  there  are  benefits  in  reduced 
training  costs  and  greater  productivity.  In  the  case  that  the  same  programmer  creates  the 
Ada  application  and  the  SQL  module,  he  is  able  to  separate  the  concerns  of  the  application 
logic  and  the  database  logic.  When  designing  or  writing  the  application  he  can  ignore  the 
issues  of  database  interaction;  when  dealing  with  the  database  he  can  concentrate  solely  on 
it.  In  both  cases,  since  the  resulting  Ada  application  program  contains  no  SQL,  it  is  isolated 
from  changes  in  the  database  structure  and  the  SQL  statements.  This  isolation  decreases 
the  cost  of  maintenance  and  porting. 

Large,  complex  database  applications  have  extensive  design  phases.  Modular  approaches 
such  as  the  SAME  are  particularly  well  suited  for  such  applications.  The  module  makes  the 
database  services  needed  by  the  application  visible.  It  is  an  application-specific,  DBMS- 
independent  interface  between  the  database  and  the  application,  which  is  naturally  treated 
during  the  design  as  a  design  object.  The  dependence  of  the  application  on  the  database 
can  be  controlled  more  easily  since  it  is  more  visible,  not  scattered  throughout  the  appli¬ 
cation  as  in  non-modular  approaches.  The  module  is  an  external  schema  [6],  a  “simple  user 
view,  tailored  to  the  requirements  of  a  specific  application”  [8]. 

The  benefits  of  modular  interfaces  are  summarized  in  the  following  list. 

•  Maintenance  and  porting  costs  are  reduced  by  the  isolation  and  separation  of 
the  Ada  code  from  the  SQL  code.  The  application  -  database  interaction  is 
elevated  to  the  status  of  a  design  object.  This  makes  it  easier  to  manage  and 
control. 


’The  method  proposed  by  the  Institute  for  Defense  Analysis  (IDA)  [12]  does  not  embed  SQL  into  Ada  in  the 
standard  sense,  but  it  doep  produce  application  programs  containing  intermixed  application  and  database  logic. 
This  is  done  by  modifying  the  syntax  and  semantics  of  SQL  so  that  it  appears  as  compilable  Ada  code.  The 
necessary  support  packages  and  system  software  are  expensive  in  development,  compilation,  and  runtime 
costs,  although  accurate  figures  are  not  available.  By  separating  the  Ada  and  the  SQL  and  allowing  each  to  be 
processed  by  pre-existing  processors,  the  SAME  avoids  these  modifications  and  expenses  entirely. 


•  The  potential  exists  tor  increased  specialization  of  the  software  development 
team.  Fewer  programmers  need  to  know  the  details  of  the  database  assign. 

This  can  lead  to  improvements  in  team  productivity. 

•  Ada  application  programs  are  written  in  compilable  Ada,  preserving  the  use  of 
syntax -directed  editors,  etc.  There  is  no  need  for  pre-processing.  There  is  no 
need  to  develop  any  new  syntax  nor  system  software;  these  methods  can  be 
used  with  existing  tools.2 

The  SAME  is  a  specialization  of  the  modular  approach  particular  to  the  needs  of  Ada.  The 
benefits  which  it  brings  to  database  applications  written  in  Ada  are: 

•  The  Ada  typing  model.  Using  the  SAME  method,  the  Ada  program  views  the 
database  through  the  abstract  type  facilities  of  Ada.  Type  derivation  and  sub¬ 
typing  are  available  as  are  range  constraints  to  control  runtime  behavior  and 
inappropriate  operand  usage. 

•  A  safe  treatment  of  null  values.  SQL  supports  partial  and  incomplete  infor¬ 
mation  through  the  use  of  the  null  value.  The  null  value  is  a  concept  foreign  to 
Ada,  as  it  is  to  most  programming  languages.  Through  the  use  of  Ada's  data 
abstraction  mechanism,  the  SAME  brings  a  measure  of  incomplete  information 
processing  to  Ada  while  ensuring  that  null  values  are  never  used  as  though 
they  were  not  null. 

•  A  simple,  robust,  yet  flexible  treatment  of  database  exceptional 
conditions.  SQL  database  management  systems  signal  the  occurrence  of  ex¬ 
ceptional  events,  such  as  hardware  failure,  through  a  status  code  field.  The 
meanings  of  the  values  of  that  field  are  not  set  by  the  standard;  each  implemen¬ 
tation  presents  a  different  set  of  values.  Usually  the  application  program  cannot 
recover  from  any  of  these  conditions.  The  SAME  treatment  of  exceptional  con¬ 
ditions  presents  a  failure-free  DBMS  to  the  application  program;  if  an  SQL 
statement  encounters  an  unexpected  condition,  an  exception  is  raised  and  an 
appropriate  error  message  is  generated.  This  simplifies  the  application 
programmer’s  job  and  ensures  uniform  treatment  of  errors.  On  the  other  hand, 
the  SAME  allows  applications  which  need  to  do  some  or  all  of  their  own  error 
processing  full  access  to  the  DBMS  facilities. 

The  features  in  the  above  list  are  implemented  in  a  thin  interface  layer,  called  the  abstract 
module.  In  Figure  1-3,  the  concrete  module  is  the  object  containing  solely  SQL  statements 
as  might  be  processed  by  an  SQL  module  language  compiler.3  The  abstract  module  serves 
to  transform  data  and  procedural  abstractions  of  the  Abstract  and  Concrete  Interfaces  of 
Figure  1-3.  The  architecture  of  Figure  1-3  is  specific  to  the  manual  implementation  of  the 
SAME  method.  The  SAME  Design  Committee  (SAME-DC)  is  engaged  in  the  task  of  speci¬ 
fying  the  syntax  and  semantics  of  a  tool  to  assist  in  the  construction  of  abstract  interfaces. 
When  such  tools  become  available,  the  situation  simplifies  to  that  given  in  Figure  1  -4.  The 
SAME  method  is  valuable  without  such  tooling,  but  is  easier  to  use  with  it. 


^This  will  depend  on  the  tool  sets  supplied  by  particular  Ada  compiler  and  DBMS  vendors.  It  is  always  possible 
to  use  the  method:  these  tool  sets  may  make  it  easier. 

3As  of  this  writing,  there  are  no  compilers  for  the  SQL  module  language,  although  there  are  some  unaer 
development  that  are  due  to  be  released  soon.  In  later  chapters  we  show  how  to  build  applications  in  SAME 
without  a  module  language  cmpiler. 
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Figure  1-3:  The  Manual  Method 
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Figure  1-4:  The  Automated  Method 
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1.2.  An  Example  of  the  SAME  Method 

This  section  provices,  by  way  of  example,  an  overview  of  the  SAME  in  use.  It  is  meant  to 
provide  the  reader  with  an  intuitive  feel  for  the  method.  Later  sections  provide  the  details. 

Use  of  the  SAME  begins  during  the  process  of  database  design.4  Early  in  that  process  the 
designer  oelineates  the  abstract  domains  of  his  database.  The  notion  of  an  abstract  domain 
is  very  similar  to  the  notion  of  an  abstract  type.  However,  the  Ada  definition  of  an  abstract 
domain  requires  more  than  a  single  Ada  type  definition,  as  will  be  shown.  Hence,  a  new 
term  was  needed  to  define  this  concept. 

Abstract  domains  are  objects  in  the  real  world  that  are  reflected  in  the  information  system 
which  models  that  world.  They  are  also  the  objects  from  which  the  database  structures,  that 
is,  the  relations,  will  be  built.  They  describe,  inter  alia,  the  value  sets  which  may  appear  in 
database  columns.  Like  Ada  types,  abstract  domains  serve  to  distinguish  differing  denota¬ 
tions  of  a  concrete  value;  the  value  “1”  as  an  employee  number  is  not  the  same  as  the 
value  “1 "  as  a  department  number,  for  example. 

Abstract  domains  tend  to  lose  their  identities  in  the  SQL  schema  due  to  SQL’s  weak  typing 
model.  Ada's  typing  model  allows  these  domains  to  retain  their  identities  and  the  SAME 
exploits  that  power. 

Entity  relationship  diagrams  [7]  are  a  popular  database  design  aid.  Figure  1  -5  contains  such 
a  diagram,  deciding  me  parts-suppliers  database  of  C.  J.  Date  [9].  The  diagram  describes 
two  entities:  Suppliers,  uniquely  identified  by  Number  and  having  attributes  Name,  Status 
and  City;  Parts,  also  uniquely  identified  by  Number,  with  attributes  Name,  Color,  Weight, 
and  City.  (The  city  of  a  supplier  is  the  city  in  which  the  supplier  is  located;  the  city  of  a  part 
is  the  city  in  which  the  part  is  stored.)  The  diagram  also  recognizes  one  relationship,  Order, 
which  relates  a  supplier  and  a  part,  and  has  the  attribute  Quantity. 

Designing  the  abstract  domains  in  a  database  design  is  much  like  designing  the  abstract 
data  types  of  an  Ada  program.  A  good  rule  of  thumb  to  follow  is  the  comparison  rule.  If  it 
makes  sense  to  compare  values  of  two  different  Ada  variables  or  database  attributes,  then 
they  probably  have  the  same  Ada  type  or  abstract  domain.  For  example,  it  makes  no  sense 
to  compare  supplier  numbers  to  part  numbers;  part  number  one  is  utterly  different  from  sup¬ 
plier  number  one.  The  same  is  true  for  supplier  and  pad  name...  On  the  other  hand,  supplier 
cities  and  part  cities  have  the  same  abstract  domain;  "Pittsburgh”  is  "Pittsburgh”  whether  a 
supplier  or  a  part  is  located  there.  Thus,  the  abstract  domains  in  Figure  1  -5  are  supplier 
number  (SNO),  supplier  name  (SNAME),  STATUS,  CITY,  part  number  (PNO),  pad  name 
(PNAME),  COLOR,  WEIGHT,  and  quantity  (QTY). 


The  SQL  schema  for  this  database  is  given  in  Figure  1  -6.  Notice  that  the  abstract  domains 
have  been  obscured.5  SNO  and  PNO  have  the  same  data  type,  although  they  take  values 
from  distinct  abstract  domains.  The  SAME  Ada  types  for  these  columns  makes  the  distinc- 


4These  steps  are  easily  retro-fitted  to  a  pre-existing  database  design. 

5ln  this  case,  the  domains  have  been  preserved  in  the  attribute  names.  In  general,  relational  database  design 
methods,  and  SQL  in  particular,  do  not  recognize  abstract  domains. 
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Figure  1-5:  An  E-R  Diagram  for  Parts  and  Suppliers 
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Figure  1-6:  The  Parts-Suppliers  Schema 

tion  apparent.  The  full  set  of  type  declarations  for  some  of  these  abstract  domains  is  given  in 
Figure  1  -7.  The  meanings  of  these  definitions  is  not  immediately  obvious;  they  will  be  ex¬ 
plained  in  Chapters  2  and  3. 

Although  the  SAME  is  a  method  for  interfacing  Ada  and  SQL  and  not  a  tool  set,  it  does  have 
underlying  support  software.  This  software  is  known  collectively  as  the  SAME  standard 
packages.  The  packages  SQL_Char_Pkg  and  SQL_lnt_Pkg  are  two  of  these  packages.  A 
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complete  listing  of  the  specification  and  bodies  of  these  packages,  along  with  a  quick  refer¬ 
ence  guiae  to  them,  are  attached  as  Appendix  A.6 

With  SQL_Char_Pkg;  With  SQL_Int_Pkg; 
package  Example  Definitions  is 

type  PNONN_Bas«  is  new  SQL_Char_Pkg  .  SQL_Char_Not_Null ; 
subtype  PNO_Not_Null  is  PNONN_Ba«e  (1..5); 
type  PNO  Base  is  new  SQL_Char_Pkg . SQL_Char ; 
subtype  PNO  Type  is  PNO_Ba»e  (PNO_Not_Null '  Length)  ; 
package  PNO  Op*  is  new 

SQL_Char_Pkg . SQX_Cliar_OpB (PNO_Baae,  PNONN_Ba»e) ; 


type  CITXNN_Ba«e  is  new  SQL_Char_Pkg . SQL_Ch*r_Not_Null ; 
subtype  CITY_Not_Null  is  CITYNN_Ba8*  (1..15); 
type  CITY_Ba»e  isTieW  SQL_Char_Pkg . SQL_Char ; 
subtype  CITY_Type  is  CITY~Ba«e  (CITY_Not_Null ' Length) ; 
package  ciTY_Op«  is  new 

SQL_Char_Pkg. SQL_Char_Op» (CITY_Ba»e,  CITYNN_BaB«) ; 

type  Statu«_Not_Null  is  new  SQL_Int_Pkg. SQL_Int_Not_Null ; 
type  Status  Type  is  new  SQL_Int_Pkg . SQL_Int; 
package  statu«_Op*  is  new 

SQL_Int_Pkg . SQL_Int_Ops (Statu*_Type ,  Statu»_Not  Null); 
end  Exanple_Defxni.ti.one  ; 

Figure  1-7:  Some  of  the  Abstract  Domains  as  Ada  Types 

In  Figure  1  -7,  each  of  the  illustrated  abstract  domains  has  two  Ada  types.  One  of  the  types, 
with  the  suffix  _Not_Null,  is  a  visible  Ada  type;  thus  Status_Not_Null  is  an  integer  type; 
PNO_Not_Null  is  a  one  dimensional  array,  of  a  character  type.7  The  other  type,  with  the 
suffix  _Type,8  is  a  limited  private  type.  This  type  provides  an  encapsulation  of  the  SQL  null 
value.  A  full  range  of  comparison  and,  for  numeric  types,  arithmetic  operators  are  defined 
for  these  types.  These  operators  implement  the  semantics  of  the  corresponding  SQL  oper¬ 
ator,  which  is  defined  for  the  null  value.  The  majority  of  these  operators  are  denved.  using 
Ada  derivation,  from  those  defined  in  the  SAME  standard  packages.  The  tew  operators 
which  cannot  be  derived  in  this  way  are  generated  by  the  generic  packages  illustrated  in 
Figure  1  -7.  This  is  done  to  reduce  compilation  time  and  runtime  storage  requirements. 

In  the  remainder  of  these  guidelines,  the  two  types  which  together  with  the  package  instan¬ 
tiation  make  up  the  declaration  of  an  abstract  domain  are  be  called  the  visible  Ada  or 
_Not_Null\ype  and  the  limited  or  _Type  type. 

Once  the  database  schema  has  been  defined  in  Ada,  subsequent  steps  of  the  SAME  are 
application  specific.  Consider  the  following  application:  "For  each  part  ordered  from  any 
supplier,  print  the  part  number  and  the  names  of  cities  in  which  some  supplier  with  a  status 
of  X or  greater  is  located.  X  is  a  runtime  parameter."  In  order  to  implement  this  application, 
an  Ada  program  will  need  three  database  procedures: 


6The  SEl  will,  for  a  limited  time,  distribute  this  software  in  machine-readable  form.  An  order  form  is  attached  to 
this  document. 

7This  type  may  be  other  than  Standard. Character,  as  the  database  may  store  non-ASCII  character  strings. 

8Section  3 .4  explains  the  need  for  the  structure  of  the  character  string  type  definitions 
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1 .  An  "open  cursor"  procedure  which  accepts  the  runtime  parameter. 

2.  A  "fetch"  procedure  to  return  the  rows  of  part  numbers  and  cities. 

3.  A  "close  cursor"  procedure  to  be  called  when  the  application  has  exhausted 
all  selected  rows. 

The  program  will  also  need  a  definition  of  the  rows  being  passed  to  it.  These  procedure  and 
row  record  definitions  make  up  the  abstract  interface,  the  specification  of  the  abstract  mod¬ 
ule.  That  specification,  for  this  example,  is  given  in  Figure  1-8. 

With  Example  Definition*;  use  Example_Def inition* ; 
package  Exampls_Intsrf*cs  is 

type  Part_Nbr_City_Pairs  is  record 
Pno  :  PNO_Not_Null; 

City  :  City_Type; 
end  record; 


—  All  of  these  procedures  may  raise  SQL  Database  Error 

procedure  Open  (Lowsr_Bound  Status_Not_Null) ; 

—  create*  the  relation  of  Part  numbers  and  Cities 
--  where  there  exrsts  some  supplier,  with  status 

—  at  least  Lower  Bound,  of  that  part  m  that  city 

procedure  Fetch  (Tuple  :  in  OUt  Part_Nbr_City_Pairs; 

Found  OUt  Boolean)  ; 

—  returns  the  record*  of  the  relation  created  by  open 
—  Found  becomes  False  at  end  of  table 


procedure  close; 

—  clean  up  procedure 
end  Example_Inter£ ace ; 

Figure  1-8:  Example  Abstract  Interface 

Once  the  abstract  interface  has  been  determined,  the  application  program  can  be  written. 
Figure  1-9  contains  the  application  program.  For  that  figure,  assume  that  StatusJO  is  an 
instantiation  of  IntegerJO  for  the  integer  type  Status_Not_Null.  The  functions  Not_Null  and 
to_unpadded_string  are  supplied  by  the  SAME  standard  packages. 

It  is  instructive  to  notice  the  differences  between  application  programs  using  an  abstract  in¬ 
terface,  as  exemplified  by  Figure  1-9,  and  one  using  the  concrete  interface  provided  by  the 
ANSI  module  language,  as  is  shown  in  Figure  1  -10.  (In  Figure  1  -10,  Example_Module  is  the 
Ada  package  name  assigned  to  the  concrete  module,  which  is  illustrated  in  Figure  1-11; 
SQl_Standard  is  a  package  defined  in  a  revised  version  of  the  ANSI  standard.  See 
[16]  [5]  and  Section  2-1 .  SQLJntJO  is  IntegerJO  instantiated  for  SQL_Standard.lnt.) 


CMU/SEI-89-TR-1 6 


11 


With  T«xt_IO;  use  T«xt_IO; 

With  Status_IO;  --  Intagar_IO  instantiatad  for  Statua_Not 
With  Example  Interface;  use  Example  Interface; 

With  Example_Def initione;  use  Example_Def initiona ; 
procedure  Example  is 

Statu«_Buf fer  :  Status_Not_Null; 

Data_Record  Part_Nt*;_City_Paire  ; 

Record  Found  Boolean; 


begin 

put ( "Enter  Statu»=>  "); 

Statue_IO . Get (Statu«_Buf fer) ;  new_line; 

put ("Part  Numbers  and  Cities  for  Status  "); 

Status_IO . put (Status_Buf fer) ;  new_line ; 

Open (Lower_Bound  =>  Status_Buf fer) ;  —  create  result  table 

loop 

fetch (Data_Record,  Record  Found);  —  next  record  into  buffer 
exit  when  not  R«cord_Found;  —  if  exit  taken,  all  done 
If  Not_Null (Data_Record . City)  then  —  filter  out  unknown  cities 
put_line (to_unpadded_string (Data_Record . Pno)  &  "  "  S 

to_unpadded_string (Data  Record . City) ) ; 
end  if;  ~ 

end  loop; 

close; 

end  Example; 

Figure  1-9:  An  Application  Program  Using  an  Abstract  Interface 
These  differences  are  summarized  in  the  following  list. 

•  Using  an  abstract  interface,  an  application  program  treats  rows  of  a  table  as  an 
oDject  of  a  record  type.  At  the  concrete  interface,  the  components  of  a  row  are 
treated  as  individual  parameters. 

•  Using  an  abstract  interface,  an  application  program  sees  the  database  through 
the  abstract  domains  identified  during  database  design.  At  the  concrete  inter¬ 
face,  only  the  limited  set  of  SQL  types  are  present. 

•  Using  an  abstract  interface,  an  application  programmer  may  safely  remain  un¬ 
aware  of  the  SQL  conventions  for  null  values.  At  the  concrete  interface,  sepa¬ 
rate  indicator  variables  signal  nullness.  Obscure  errors  can  result  from  mishan¬ 
dling  these  indicators.  These  errors  cannot  arise  in  programs  using  the  SAME. 

•  Using  an  abstract  interface,  an  application  program  does  not  see  the 
SQLCODE  parameter.  This  is  the  variable  which  holds  the  status  code  returned 
from  every  SQL  statement  execution.  At  the  concrete  interface,  the  application 
must  check  this  parameter,  understand  it,  and  execute  application  supplied  er¬ 
ror  processing  if  things  go  wrong.  Obscure  errors  can  result  from  not  handling 
these  DBMS  exceptional  conditions  correctly.  These  errors  are  eliminated  from 
programs  using  the  SAME. 

It  is  also  worth  noting  that  the  abstract  interface  provides  facilities  which  permit  application 
programs  to  be  indifferent  to  the  encoding  of  the  character  data  in  the  database.  The  con¬ 
crete  interface  supports  the  use  of  non-ASCII  characters  but  provides  no  mechanism  for 
inter-converting  them  with  ASCII  characters.  For  example,  the  Ada  explicit  type  conversions 
(that  appear  as  arguments  to  the  putjine  call  in  Figure  1  -10)  assume  that  the  DBMS  stores 
ASCII  character  strings.  In  contrast,  the  corresponding  portion  of  Figure  1  -9  uses  an  ab¬ 
stract  interface  function  (tojjnpadded_string)  which  will  convert  the  DBMS  character  set  to 
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ASCI!  if  needed.  (The  decision  is  made  as  part  of  the  installation  of  the  SAME  support 
packages.  See  [14].) 

With  T«xt_IO:  use  Text_IO; 
with  SQL_Int_IO; 

With  Exampl«_Modul«;  use  Exampl»_Modul« ; 
with  SQL^StaxKiaxd; 

procedure  Example_at  Conor«t«_Intar£ ace  is 

Sfcatua  Buff»r  SQL_St.andard.Int; 

Part_Numb«r :  SQL_Standar d . Char ( 1 . . 5 ) ; 

City:  SQL_Stand*rd . Char (1 . . 15) ; 

SQLCODE  :  SQL_Standard . SQLCODE_Typa ; 

City_Indicator  :  SQL _ Standard. Indicator _ Typa; 

begin 

put ("Enter  Statua=>  "); 

SQL_Int_IO . Get (Statu«_Buf f er ) ;  new_line; 
put("Part  Numbers  and  Cities  for  Status  ") ; 

SQL  Int  IO .put (Statua_Bu£ f er ) ;  new_line; 

Open (Status_Buff er ,  SQLCODE); 
if  SQLCODE  in  SQL_Standard.  SQL_Error  then 

<application  supplied  error  processing> 

else 

loop 

fetch (Part_Number,  City,  City_Indicator ,  SQLCODE) ; 

If  sqlcode  =  o  then 

if  City_Indicator  >=  0  then 

put_line (string (Part_Number)  i  "  ”6 

string (City) ) ; 

end  If; 

elsif  SQLCODE  in  SQL_Standard.SQL_Error  then 
•Application  supplied  error  prc.assing> 
exit; 

elsif  SQLCODE  In  SQL_Standard.Not_Found  then 
exit; 
end  If; 
end  loop; 
end  If; 
close; 

end  Exampla  at  Concrete  Interface; 

Figure  1-10:  Application  Using  Concrete  Interface 

There  remains  now  only  the  task  of  creating  the  body  of  the  abstract  interface,  also  called 
the  abstract  module.  The  purpose  of  the  procedures  in  that  module  is  to  form  the  bridge 
between  the  concrete  interface  and  the  abstract  interface.  It  is  assumed  in  this  section  that 
the  concrete  interface  is  supplied  by  a  module  language  compiler  that  is  compliant  with  the 
ANSI  standard.  The  SAME  does  not  depend  on  the  existence  of  such  compilers.  Chapter  7 
demonstrates  the  use  of  the  SAME  in  environments  without  such  compilers. 

Figure  1-1 1  contains  the  specification  of  the  concrete  module  for  the  example  as  it  would  be 
written  in  the  module  language.  The  Ada  package  specification  corresponding  to  that  mod¬ 
ule,  according  to  the  revised  ANSI  standard  [5]  [16],  appears  in  Figure  1-12.  The  body  of 
that  package  is  implementation  dependent;  in  particular,  its  form  will  depend  on  the  tool  set 
available  for  the  DBMS  is  use.  Finally,  the  abstract  module,  implementing  the  abstract  inter¬ 
face  on  top  of  the  concrete  interface,  appears  in  Figure  1  -1 3. 
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Module  Example  Module 
Language  Ada 
Authorization  Public 

Declare  X  Cursor 
For 

Select  SP.PNO,  S . City 

From  SP ,  S 

Where  SP . SNO  =  S . SNO 

And  S. Status  >=  Input_Status; 

Procedure  X  Open 

Input_Status  Int 
SQLCODE ; 

Open  X; 

Procedure  X_Fetch 

Part_Number  Char ( 5 ) 

City  Char (15) 

City_Indic  Smallint 
SQLCODE ; 

Fetch  X  into  P«rt_Number,  City  INDICATOR  City_Indic; 

Procedure  X  Close 
SQLCODE; 

Close  X; 

Figure  1-11 :  The  Concrete  Module  for  the  Example 

With  SQL_Standard; 
package  Examp le_Module  is 

procedure  X_Open  (Input_Status  :  SQL_Standard . Int ; 

SQLCODE  :  OUt  SQL_Standard . SQLCODE JType)  ; 

procedure  X_Fetch  (Part_Number  ;  out  SQL_Standard . Char ; 

City  :  OUt  SQL_Standard.Char; 

City_Indic  :  OUt  SQL_Standard . Indicator  Type; 

SQLCODE  :  out  SQL_StXndard.  SQLCODE_Type"j\- 

procedure  X_Cloee  (SQLCODE  :  OUt  SQL_Standard.SQLCODE_Type) ; 

end  Example  Module; 

Figure  1-12:  Ada  Specification  of  Concrete  Module  --  The  Concrete  Interface 

The  detail  in  Figure  1-13  (for  example,  the  purpose  of  the  packages 
SQL_Communications_Pkg  and  SQL_Database_Error_Pkg)  is  explained  in  Chapter  4, 
whic(  explains  the  construction  of  abstract  modules.  The  outline  of  an  abstract  interface 
procedure  body  can  be  recognized  in  Figure  1-13.  That  outline  is  described  by  the  following 
list. 
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1  .'The  corresponding  procedure  in  the  concrete  interface  is  called.  Any 
parameters  to  that  procedure  are  convenea  to  the  appropriate  type  in  package 
SQL_Standard. 

2.  The  resulting  status  code  parameter  (SQLCODE)  is  examined.  If  the  value  of 
that  parameter  lies  in  a  set  of  expected  values,  control  is  returned  to  the  appli¬ 
cation  program.  Otherwise,  a  standardized  error  processing  routine  is  called 
and  an  exception  is  raised. 

3.  Values  which  may  be  null  are  checked  for  nullness,  converted  to  the  appro¬ 
priate  types  for  the  application  program  and  assigned  to  the  output  row  record. 
Values  which  may  not  be  null  are  placed  directly  into  the  output  row  record  by 
the  concrete  procedure.  (In  the  case  of  insert  or  update  SQL  statements,  for 
which  data  flows  from  the  application  to  the  database,  this  set  of  steps  occurs 
first.) 

The  fact  that  every  abstract  interface  procedure  body  has  a  predictable  structure  makes 
them  prime  candidates  for  automatic  generation.  The  SAME  Design  Committee  hopes  to 
create,  in  the  near  term,  a  notation  enhancing  the  standard  ANSI  module  language,  within 
which  abstract  interfaces  can  be  described  and  from  which  they  can  be  generated.  This  is 
the  idea  behind  Figure  1-4. 


1.3.  Structure  of  This  Document 

The  remainder  of  these  guidelines  presents  the  SAME  in  detail.  Chapters  2  and  3  tell  the 
database  designer  how  to  describe  the  database  in  terms  of  the  abstract  types  used  by  the 
SAME.  Chapter  4  gives  the  information  needed  by  the  builder  of  abstract  interface  modules. 
Chapter  5  contains  hints  and  suggestions  for  designers  and  programmers  of  applications 
using  the  SAME.  Much  of  the  information  in  Chapter  5  also  appears  elsewhere  in  the  guide¬ 
lines.  It  is  repeated  in  Chapter  5  for  the  convenience  of  application  programmers.  Chapter 
6  contains  a  condensed  overview  of  the  SAME.  The  bulk  of  this  document  assumes  the 
existence  of  a  compiler  for  the  ANSI  standard  module  language.  Use  of  the  SAME  does  not 
require  such  a  compiler.  Chapter  7  describes  how  the  SAME  can  be  used  without  a  module 
language  compiler.  Chapter  8  contains  an  extended  example  of  the  SAME.  Chapter  9  de¬ 
scribes  the  use  of  the  SAME  in  applications  which  use  dynamic  SQL  or  Ada  multi-tasking. 

The  SAME  is  supported  by  the  SAME  standard  packages.  A  complete  listing  of  these  pack¬ 
age  specifications,  along  with  suggested  package  bodies,  apoears  in  Appendix  A.  There  are 
also  appendices  containing  a  quick  reference  guide  and  a  glossary  of  terms. 
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with  SQL_Standard,  Example  Module,  Exaiiple_D«finitiona , 

SQL  Communications  Pkg,  SQL  Database  Error  Pkg; 
use  SQL_Standard; 

package  body  Example  Interface  IS 

package  ExMod  renames  Examp le_Module; 
package  SCP  renames  SQL  Communications_Pkg; 
package  SDEP  renames  SQL_Database_Error_Pkg; 
package  ExDef  renames  Example_Def initions ; 

procedure  Open  (Lower_Bound  :  Status_Not_Null)  is 
begin 

ExMod. X_Open (Int (Lower_Bound) ,  SCP . SQLCODE) ; 
if  SCP. SQLCODE  in  SQL_Error  then 

SDEP . Proceas_Databaae  Error; 
raise  SCP . SQL_Database_Error; 

end  If; 
end  Open; 

procedure  Fetch  (Tuple  ;  in  out  Part_Nbr_City_Pairs; 

Found  :  out  Boolean)  is 
City_Buf  :  Char  (ExDef .CITY_Not_Null ' Range ) ; 

City_Indic  :  Indicator_Type; 
begin 

ExMod. X_Fetch(Char (tuple .Pno) ,  City_buf,  City_Indic,  SCP . SQLCODE ) ; 

case  scp. sqlcode  is 
when  Not_Found  => 

Found  : =  false; 
when  SQL_Error  => 

SDEP .Proees*_Database_Error; 
raise  SCP.SQL_Database_Error; 
when  o  => 

if  City_Indic  <  0  then 

assign (tuple . City,  Null_SQL_Chax) ; 

else 

assign (tuple . City, 

City_Ops . With_Null (City_Not_Null (City_Buf ) ) ) ; 

end  If; 

Found  : *=  true; 

when  others  =>  null;  —  standard  has  no  such  codes 
end  case; 
end  Fetch; 

procedure  close  is 
begin 

ExModX_Close( SCP. SQLCODE) ; 
if  SCP. SQLCODE  in  SQL_Error  then 

SDEP .Process_Database  Error; 
raise  SCP . SQL_Database2Error ; 

end  If; 
end  Close ; 

end  Example_Inter£ace ; 

Figure  1-13:  Body  of  the  Abstract  Interface  --  The  Abstract  Module 
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2.  The  SAME  Typing  Model 

This  section  describes  the  model  of  data  typing  employed  by  the  SAME.  The  model’s  objec¬ 
tive  is  to  integrate  the  data  semantics  of  Ada  and  SQL  to  the  extent  that  is  desirable  and 
practicable.  The  problems  to  be  solved  in  such  an  integration  are: 

•  The  differences  between  the  typing  models  of  Ada  and  SQL.  SQL  offers  a 
limited  set  of  primitive  data  types.  It  does  not  offer  a  mechanism  for  user- 
defined  types.  The  abstract  typing  mechanisms  of  Ada  are  a  central  aspect  of 
the  language.  An  Ada  program  prefers  a  view  of  the  database  contents  consis¬ 
tent  with  a  set  of  abstract,  application-oriented  types. 

•  The  null  value.  SQL  provides  a  means  of  processing  missing  or  incomplete 
information.  This  is  the  null  value  and  three-valued  logic.  These  notions  do  not 
appear  in  Ada. 

•  String  processing.  Ada  and  SQL  give  subtly  different  semantics  to  the  string 
comparison  operators.  Further,  the  Ada  predefined  type  string  is  by  definition  a 
sequence  of  ASCII  characters.  SQL  strings  are  over  an  implementor-defined 
character  set. 

•  Decimal  fixed  point  arithmetic.  Ada  fixed  point  arithmetic  does  not  resemble 
SQL  decimal  arithmetic.  More  importantly,  Ada  compilers  do  not  recognize  the 
machine-specific  packed  decimal  formats  in  which  SQL  database  management 
systems  store  decimal  data. 

•  Non-standard  data  types.  Many  database  management  systems  recognize 
data  types  not  in  the  ANSI  standard.  The  date-time  data  type  is  an  example  of 
this.  Ada  programmers  may  wish  to  store  enumeration  types  in  SQL  data¬ 
bases,  even  though  SQL  does  not  recognize  such  types. 

The  SAME  solution  to  these  problems  aims  at  good  performance  in  both  time  and  space.  It 
achieves  a  direct  mapping  between  SQL  and  Ada  types  [1 1]  which  requires  no  data  conver¬ 
sions.  Each  bit  pattern  representing  a  non-null  value  of  a  database  column  represents  the 
same  value  of  the  Ada  data  type  which  describes  it.9 

The  SAME  typing  model  is  flexible.  An  overview  of  it  is  given  in  Figure  2-1 .  At  the  lowest  or 
concrete  level  of  the  interface,  at  which  the  calls  to  the  concrete  DBMS  module  appear, 
database  values  are  described  by  Ada  types  designed  in  conformance  with  SQL  require¬ 
ments.  These  types  are  reviewed  in  the  next  subsection.  Except  for  Chapter  7,  these  guide¬ 
lines  assume  a  compiler  for  the  module  language  conforming  to  the  recommendations  in 
[16]  which  are  incorporated  in  [5].  In  Chapter  7,  techniques  are  presented  for  low  cost  im¬ 
plementations  of  SAME  in  environments  withou.^  module  compiler. 

As  shown  in  Figure  2-1,  the  concrete  types  at  the  concrete  level  are  transformed  into  ab¬ 
stract  types  at  the  abstract  level.  The  three  branches  of  that  diagram  represent  three  differ¬ 
ent  treatments  of  data  semantics. 


^he  Ada  application  program  sees  the  database  through  a  set  of  abstract,  application-oriented  types.  These 
types  and  their  derivation  are  described  in  Chapter  3.  This  section  is  concerned  with  the  concrete  representation 
of  database  values. 
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•  Ada  semantics.  Each  database  column  is  represented  by  an  Ada  type  whose 
arithmetic,  comparison,  arid  assignment  operations  are  those  of  Ada.  With 
these  semantics,  treatment  of  database  and  non-database  data  is  uniform 
throughout  the  Ada  program. 

•  SQL  semantics.  Each  database  coiumn  is  represented  by  an  Ada  type  whose 
arithmetic,  comparison,  and  assignment  operations  simulate  those  of  SQL.  With 
these  semantics,  treatment  of  database  data  is  uniform  between  the  SQL  and 
Ada  portions  of  the  complete  application. 

•  User-defined  semantics.  Each  database  column  is  represented  by  an  Ada 
type  whose  arithmetic,  comparison,  and  assignment  operations  are  user  de¬ 
fined.  This  treatment  allows  for  user  extensions  of  the  method. 

The  choice  of  treatment  is  the  responsibility  of  the  application  designer.  This  section  de¬ 
scribes  the  realization  of  those  semantic  treatments. 

As  mentioned,  the  next  section  reviews  the  concrete  treatment  of  SQL  data.  It  is  this  treat¬ 
ment  which  achieves  the  direct  mapping  mentioned  earlier.  Chapter  3  describes  the  devel¬ 
opment  of  the  abstract  domains.  Section  3.1  discusses  the  treatment  of  null  values  in  the 
SAME  and  how  that  affects  application  programs.  Section  3.3  continues  that  discussion, 
showing  how  the  abstract  types  implementing  SQL  semantics  can  be  arranged  into  type 
hierarchies  and  Ada  range  constraints  can  be  simulated  for  them.  Section  3.4  gives  the 
additional  information  needed  to  understand  SQL  strings  and  thcfr  SAME  implementation. 
Section  3.5  explains  the  SAME  simulation  of  SQL  decimal  fixed  point  arithmetic  and  Section 
3.6  describes  the  treatment  of  data  types  not  covered  in  the  ANSI  standard.  An  implemen¬ 
tation  of  a  date-time  data  type  and  implementations  of  support  for  SQL  storage  of  Ada 
enumeration  ./pes  are  presented  in  Section  3.6.  The  section  serves  as  a  model  for  user 
extensions  to  the  SAME  typing  model. 

The  sections  described  above  each  deal  with  individual  columns  in  isolation.  Section  3.7 
puts  the  results  of  those  sections  together  into  a  description  of  the  database. 
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Ada  Application  Program 


Ada  SQL  User-Defined 

Semantics  Semantics  Semantics 


Figure  2-J:  The  SAME  Typing  Model 


2.1.  Concrete  Types 

At  the  lowest,  or  concrete,  level  of  the  SAME  SQL  Ada  interface,  the  level  at  which  the  calls 
to  concrete  module  routines  appear,  all  parameters  have  types  which  appear  in  the  package 
SQL_STANDARD.  This  package  was  created  Dy  the  SAME  Design  Committee  (SAME-DC)  as 
a  recommended  change  to  the  ANSI  SQL  interface  to  Ada  [16]  [3]. 10  A  listing  of  this  pack¬ 
age  appears  in  Figure  2-2.  Each  type  definition  in  sql_Standard  directly  defines  the  SQL 
type  with  the  same  name.11  The  definition  is  direct  in  the  sense  used  previously:  the  value 
sets  underlying  the  types  in  sql_standard  are  exactly  the  value  sets  underlying  the  cor¬ 
responding  SQL  types.  Further,  under  reasonable  assumptions,12  the  data  encodings  will  be 
identical  and  no  data  conversion  will  be  necessary. 

All  of  this  is  achieved  by  judicious  choice  of  the  implementor-defined  values  in 
sql_st  an  da  r  d  .  These  values  are  specific  to  the  database  management  system  in  use. 

Once  they  have  been  determined,  the  package  will  be  compiled  as  part  of  the  installation 
procedures  for  the  SAME  standard  packages  into  an  Ada  library  within  which  it  may  be 
referenced  by  other  SAME  standard  packages.  Application  programmers  need  not  be  con¬ 
cerned  with  this  package;  application  programs  do  not  reference  it. 


10These  recommendations  were  accepted  by  the  responsible  ANSI  subcommittee  and  appear  in  their  current 
proposal  for  Ada  support  in  SQL  [5], 

11  Although  sqicode_type  is  not  a  type  defined  in  SQL,  sqlcode  acts  as  though  it  were  a  type  as  well  as  a 
variable  in  [2]  and  [5], 

12The  assumptions  are  that  the  DBMS,  at  the  application  programming  interface,  delivers  numeric  values  in 
the  encoding  of  the  machine  and  that  the  Ada  compiler  uses  these  encodings  as  well.  This  should  be  true  in 
almost  every  case. 
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package  »ql_*tandard  is 

package  Charactar_Sat  renames  cap: 

subtype  Charact#r_Type  is  Character_Set . cat ; 
type  chax  is  array  (positive  range  <>) 
of  Character  Type; 
type  Smellint  is  range  ba..t*; 
type  int  is  range  bi..ti; 
type  Real  is  digits  dr; 
type  Double_Preci*ion  is  digits  dd; 
type  Decimal  is  to  be  determined; 
type  Sqlcode_Type  is  range  btc. .tec; 
subtype  Sql_Error  is  Sqlcode_Type 

range  Sqlcode_Type ' FIRST  ..  -1; 
subtype  Not_Found  is  Sqlcode_Type 
range  100..100,- 
SUbtype  Indicator_Type  is  t; 

cap  ia  an  implementor-defined  package  and  cat  is  an 
implementor-defined  character  type,  ba,  ta,  bi,  ti,  dr,  dd,  bac, 
and  tac  axe  implementor  defined  integral  values,  t  is  int  or 
smallint  corresponding  to  an  implementor-defined  <exact 
numeric  type>  of  indicator  parameters. 


end  sql  standard; 

Figure  2-2:  The  Package  sql_standard 

The  values  appropriate  to  the  definition  of  the  integer  and  floating  point  types  will  generally 
be  easily  available  in  the  DBMS  documentation.  Likewise  the  definition  of  sqlcodejtype 
should  not  be  difficult.  (It  is  likely  to  be  identical  to  one  of  the  integer  types.)  The  floating 
point  types  will  also  be  defined  in  the  DBMS  documentation.  It  may  also  be  necessary  to 
examine  the  documentation  for  the  Ada  compiler,  particularly  true  for  the  values  of 
System. Maxjnt  and  System. Max_Digits. 

The  treatment  of  character  data  in  SQL_STANDARD  is  meant  to  allow  for  non-ASCII  data.  The 
type  char  is  defined  on  analogy  to  the  Ada  predefined  type  string  but  with  respect  to  a 
character  type  which  can  be  specified  by  the  implementor.  To  use  these  definitions  with 
ASCII  strings,  set  csp  to  standard  and  cst  to  character. 

The  subtypes  sql_error  and  not_found  of  sqlcode_type  are  provided  for  the  benefit  of 
programmers,  such  as  authors  of  abstract  modules,  who  write  their  own  error  detection 
routines.  For  example,  one  may  write 

If  SQLCODE  is  in  Sql_Error  .  .  . 

or 

case  SQLCODE  is 
when  o  => 

—  error  free  return 
When  Not_Found  => 

--  no  record  found 
When  Sql_Error 

—  error  condition  from  DBMS 
when  other*  => 

--  atend&rd  describe*  no  such  code* 

end  case; 
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For  more  on  the  SAME  treatment  of  exceptional  conditions,  see  Chapter  4. 

The  SAME  standard  packages  also  depend  upon  the  package  sql_system  (see  Figure  2-3) 
which  defines  two  constants,  the  values  of  which  cannot  be  deduced  from  sql_standard. 
The  constant  MAXCHRLEN  is  the  length  of  the  longest  character  string  supported  by  the 
DBMS.  The  constant  MAXERRLEN  is  the  length  of  the  longest  error  message  returned  by 
the  DBMS-supplied  error  message  function.  See  Chapter  4  for  details. 

—  SQL  System  is  a  "platform-specific"  package 
—  within  the  SAME 
package  SQL_System  is 

—  MAXCHRLEN  ia  the  upper  bound  of  the  SQL_Char_Pkg 

aubtypea  SQL_Char  Length  and  SQL_Onpadded_Length 
—  SQL_Char_Length  ia  a  aubtype  of  Natural  with  a  lower  bound 
of  1 

—  SQL  0npadded_Length  ia  a  aubtype  of  Natural  with  a  lower 
--  bound  of  0 

MAXCHRLEN  :  constant  :=  str_leng; 

—  MAXERRLEN  is  the  maximum  length  of  the  error  message 
—  string  returned  from  the  DRMS  error  message  function 

MAXERRLEN  :  Constant  :=  mag_leng; 

end  SQL_System; 

Figure  2-3:  The  Package  SQL_System 

Creation  and  compilation  of  the  SQL_STANDARD  and  SQL_SYSTEM  package  specifications  are 
part  of  the  installation  of  the  SAME  standard  packages.  The  installation  guide  for  the  SAME 
standard  packages  [14]  contains  details  of  the  installation  process. 
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3.  Developing  the  Abstract  Domains 

The  types  in  sql_standard  define  the  representation  of  SQL  data  to  the  Ada  compiler.  As 
illustrated  in  Section  1.2,  applications  developed  using  the  SAME  method  view  the  database 
through  a  collection  of  abstract  domains.  These  abstract  domains  are  built  on  top  of  type 
definitions  provided  in  the  SAME  standard  packages  or  in  similar  packages  defined  by  the 
user  (see  Section  3.6). 

There  exists  a  support  package  in  the  SAME  standard  packages  for  each  of  the  types  in 
sql_standard  (except  for  sqlcode_type)  .  The  package  sql_int_pkg  gives  support  to  ab¬ 
stract  types  based  on  the  SQL  Int  type;  sql_char_pkg  supports  character  strings,  etc. 

Each  of  these  packages  defines  two  types.  One  of  these  types  is  a  visible  Ada  type  derived 
from  the  corresponding  type  in  SQL_STANDARD  with  no  added  constraints.  These  type  names 
are  formed  from  the  package  name  by  dropping  the  _Pkg  suffix  and  appending  the  suffix 
_Not_Null.  Thus,  SQL_lnt_Not_Null  is  defined  in  the  package  sql_int_pkg  as  new 
SQL_Standard.lnt;  SQL_Char_Not_Null  is  defined  in  sql_char_pkg  as  new 
SQL_Standard.Char,  etc. 

The  second  type  defined  in  each  package  is  a  limited  private  type.  These  type  names  are 
formed  by  dropping  the  _Pkg  suffix  and  adding  no  additional  suffix.  Thus  sql_int_pkg  de¬ 
fines  SQL_lnt,  sql_char_pkg  defines  SQL_Char,  etc.  These  limited  private  types  are  used 
to  support  SQL  data  semantics.  In  particular,  objects  of  these  types  can  take  on  the  SQL 
null  value,13  whereas  objects  of  the  _Not_Null  types  cannot. 

As  is  shown  in  the  introduction,  an  abstract  domain  is  represented  in  the  SAME  by  two  type 
definitions  derived,  directly  or  indirectly,  from  the  types  in  a  support  package.  (Character 
string  types  further  require  two  subtype  definitions.  These  are  explained  in  Section  3.4, 
below.)  Conventionally,  the  name  of  the  type  derived  from  the  _Not_Null  type  retains  the 
_Not_Null  suffix;  the  name  for  the  type  derived  from  the  limited  private  type  appends  the 
suffix  _Type;  these  derivations  and  naming  conventions  are  illustrated  in  Figure  1-7.  The 
types  are  referred  to  in  this  document  as  the  visible  Ada,  or  _Not_Nul  I  type,  and  the  limited 
private,  or  _ Type  type. 

The  creation  of  the  abstract  domain  definitions  completes  the  first  step  in  the  description  of 
the  database  within  the  SAME  method.  The  second  step  consists  of  collecting  the  definitions 
into  Ada  package  specifications.  These  are  called  domain  packages  and  their  formation  is 
defined  in  Section  3.7. 


3.1.  The  SAME  Treatment  of  SQL  Null  Values 

Objects  or  values  that  are  directly  or  indirectly  database  values  are  to  be  stored  as  objects 
of  one  of  the  types  making  up  an  abstract  domain  definition.  In  cases  in  which  it  is  possible 
for  these  database  values  to  take  on  the  SQL  null  value,  they  must  be  stored  as  values  of 
the  limited,  _Type  type.  In  cases  in  which  it  is  logically  certain  that  a  value  cannot  be  null, 
the  visible  _Not_Null  type  can  be  used.  This  logical  certainty  can  be  supplied  either  by  SQL 


13The  SQL  null  value  should  not  be  confused  with  the  null  value  of  an  access  tyoe  . 
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or  by  the  apolication  logic.  The  data  definition  facilities  of  SQL  can  restrict  the  value  of  a 
table  column  to  exclude  the  null  value:  the  data  manipulation  statements  of  SQL  car  filter 
out  rows  with  null  values  in  specified  columns.  Within  an  application,  it  may  be  logically  cer¬ 
tain  that  null  values  have  been  previously  filterea  out.  If  the  aDsence  of  the  null  value  is  not 
logically  certain  in  this  sense,  then  the  limited  type  must  be  used.  The  SAME  standard 
packages  are  defined  in  such  a  way  as  to  guarantee  a  runtime  error,  namely,  the  exception 
Null_Value_Error,  if  a  null  value  is  inadvertently  used  as  though  it  were  not  null. 

Consider,  then,  a  situation  in  which  the  null  value  is  logically  possible  and  a  given  object  has 
one  of  the  SAME  limited  types.  As  part  of  its  method,  the  SAME  offers  three  treatments  of 
these  objects.  These  treatments  are  coding  disciplines  enforced  on  application  program¬ 
mers.  The  SAME  allows  these  treatments  to  be  intermixed  in  an  application  program  in  any 
way,  subject  only  to  whatever  local  standards  and  guidelines  may  exist. 

3.1.1.  The  Minimalist  Approach 

In  the  minimalist  approach,  objects  of  limited  types  are  treated  solely  as  value  repositories. 
All  manipulation  of  and  access  to  the  values  of  these  objects  is  done  by  first  extracting  the 
value  from  the  limited  object  into  an  object  of  the  corresponding  visible  or_Not_Null  type. 

An  advantage  of  this  approach  is  that,  as  the  _Not_Null  types  are  visible  Ada  types,  the 
predefined  Ada  operations  may  be  used  on  objects  of  those  types.  Furthermore,  as  objects 
of  those  types  may  not  be  null,  it  is  unnecessary  to  check  for  the  null  value  when  accessing 
such  objects.  The  minimalist  approach  may  result  in  marginal  runtime  reductions.  More  im¬ 
portantly,  the  minimalist  approach  may  appear  more  natural  to  some  programmers 

Each  of  the  SAME  standard  packages  offer  two  sets  of  functions  to  support  the  minimalist 
approach.  They  are  testing  functions  and  conversion  or  extraction  functions.  The  extraction 
functions  will  raise  the  N  '_Value_Error  exception  if  applied  to  an  object  whose  value  is 
null. 

•  Testing  functions.  These  are  the  Boolean-valued  functions  ls_Null  and 
Not_Null.  These  functions  are  declared  in  the  specification  of  the  appropriate 
SAME  standard  packages  (SQL_lnt_Pkg,  etc.)  in  which  the  limited  type  and 
visible  types  are  also  declared.  Therefore,  when  the  pair  of  types  defining  an 
abstract  domain  are  derived  from  those  types,  these  subprograms  are  derived 
for  the  new  type. 

•  Conversion  functions.  These  are  the  functions  With_Null  and  Without_Null.14 
The  function  With_Null  takes  an  object  of  the  visible  _Not_Null  type  and  returns 
a  non-null  object  of  the  corresponding  limited,  _Type  type.  The  function 
Without_Nu!l  takes  an  object  of  the  limned  type  and  returns  an  ooject  of  the 
_Not_Null  type.  Without_Null  raises  the  exception  Null_Value_Error  if  its  input 
is  the  null  value. 


’dThe  character  string  support  provided  Dy  SQL_Char_Pkg  includes  other  conversion  functions  They  are 
described  in  Section  3  4. 
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Example 

Consider  the  following  fragment  of  application  logic,  referencing  the  Parts  -  Supplier  data¬ 
base  of  the  introduction.  Suppose  there  exist  two  vanables,  City,  of  type  City_Type  (a  de¬ 
rived  type  of  SQL-Char_Pkg.SQL_Char),  and  Quantity,  of  type  Quantity_Type  (derived  from 
SQL_lnt_Pkg.SQL_lnt).  In  other  words,  each  of  the  variables  may  have  the  null  value.  We 
need  to  write  a  code  fragment  which  increments  a  counter  if  the  value  of  City  is  "Pittsburgh" 
or  the  value  of  Quantity  exceeds  1 000.  Furthermore,  we  want  to  keep  a  running  total  of  the 
Quantity  values  from  rows  which  qualify  in  this  way.  Omitting  variable  declarations  for  the 
sake  of  brevity,  we  have  the  following  code  fragment  (the  variable  Sum_Quantity  has  type 
Quantity  J\lot_Null): 

If  (Not.  Null  (City)  and  then  Without_Null  (City)  =" Pittsburgh" ) 

or  else 

(Not_Null (Quantity)  and  then  Without_Null (Quantity)  >  1000) 

then 

Counter  : =  Countar  +  1; 

If  Not_Null  (Quantity)  then 

Sum_Quantity  :=  Without_Null (Quantity)  +  Suin_Quantity; 

end  If; 

end  If; 


3.1.2.  The  Full  SQL  Approach 

An  alternative  to  the  minimalist  approach  to  null  values  is  the  "full  SQL"  approach.  Using 
this  approach,  objects  of  the  _Type  types  are  accessed  and  manipulated  directly,  without 
having  to  be  extracted  or  converted  to  a  visible  Ada  type.  To  enable  this  approach,  the 
SAME  standard  packages  declare  overloaded  versions  of  the  standard  Ada  arithmetic  and 
comparison  operators.  These  versions  extend  the  semantics  of  those  operators  to  include 
the  null  value.  The  null  value  is  processed  according  to  the  rules  of  SQL.  An  application 
using  this  approach  treats  database  data  in  a  uniform  way  in  the  Ada  and  SQL  portions  of 
the  application.  To  use  the  approach,  it  is  necessary  to  unaerstand  how  SQL  processes  the 
null  value. 

SQL  defines  arithmetic  and  comparison  operators  for  sets  including  the  null  value.  The 
semantics  are  as  follows: 

•  Arithmetic:  Any  arithmetic  operation  applied  to  a  null  value  results  in  the  null 
value;  otherwise,  the  operation  is  defined  to  be  the  same  as  the  Ada  operation 
for  the  integer  and  floating  point  types.  (See  also  Section  3.5  for  decimal 
arithmetic.) 

•  Comparison:  The  comparison  of  any  value  to  the  null  value  results  in  a  new 
truth  value  called  unknown;  otherwise  the  operation  is  defined  as  in  Ada  for  the 
integer  and  floating  point  types.  (See  Section  3.4  for  the  string  comparisons.) 

The  overloaded  operators  provided  by  the  SAME  standard  packages  implement  these 
semantics.  The  comparison  operators,  Equals,  Not_Equals,  <,  <=,  etc.,  return  objects  of 
type  Boolean_With_Unknown.  This  is  an  Ada  enumeration  type  with  value  set  (FALSE,  UN¬ 
KNOWN,  TRUE).  The  SAME  standard  package  SQL_Boolean_Pkg  contains  declaration  of 
the  Boolean  functions  and,  or,  not  and  xor  defined  on  this  type  which  implement  the  three¬ 
valued  logic  of  SQL.  The  definitions  of  these  functions  in  three-valued  logic  are  given  by  the 
truth  table  in  Figure  3-1 . 
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ABA  and  B  A  or  B  A  xor  B  not  A 

T  T  T  T  F  F 

T  F  F  T  T  F 

F  F  F  F  F  T 

T  U  U  T  U  F 

F  U  F  U  U  T 

U  U  U  U  U  U 

T  -  true  F  -  false  U  -  unknown 

Rows  not  shown  follow  by  symmetry 


Figure  3-1:  Three-Valued  Logic 

Example 

The  prior  example  concerning  Cities  and  Quantities  can  be  recoded  as 

With  SQL_Bool*an_Pkg;  Use  SQL_Bool**n_Pkg; 

If  I*_Tru* (Equal* (City,  With_Null ( "Pitt*burgh” ) )  or 
Quantity  >  With_Null (1000) )  then 
Countar  :=  Countar  +  1; 

If  Not_Null  (Quantity)  then 

aaaign (Sum__Quantity,  Quantity  +  Sum_Quantity) ; 

end  If; 

end  If; 

This  encoding  is  functionally  equivalent  to  the  prior  encoding.  The  Counter  will  be  incre¬ 
mented  under  the  same  circumstances  as  before;  namely,  when  at  least  one  of  City  or 
Quantity  has  the  proper  value.  This  encoding  illustrates  mixed  usage  of  the  two  treatments. 
The  final  value  of  Sum_Quantity,  now  of  type  Quantity_Type,  will  be  the  sum  of  all  non-null 
quantities  encountered.  Had  the  test  for  the  null  value  not  been  present,  and  had  a  null 
value  been  encountered,  the  result  would  be  the  null  value.  This  treatment  of  summing  is 
equivalent  to  the  SQL  sum  set  function  which  also  sums  columns  of  data  after  filtering  out 
null  values. 

3.1.3.  A  Compromise  Approach  for  Comparison  Operators 

This  section  considers  only  the  comparison  operators,  e.  g.,  =,  >,  >=,  etc.,  and  offers  a  third 
alternative  to  their  use.  One  of  the  difficulties  with  the  comparison  operators  described  in 
Chapter  3.1.2  is  that  the  values  they  return  are  not  of  the  predefined  type  Boolean.  This 
means  that  predicates  formed  with  these  operators  cannot  appear  as  the  condition  of  an  if 
statement  unless  they  are  first  converted  to  Boolean  using  one  of  the  functions  !s_True, 
ls_False  or  IsJJnknown  defined  in  SQL_Boolean_Pkg,  as  was  shown  in  the  prior  example. 
Further,  since  the  rules  of  Ada  require  that  any  overloading  of  the  equality  operator  "=" 
return  Boolean,  the  three-valued  equality  comparison  function  must  be  coded  as’the  prefix 
function  Equals  and  its  complement  as  the  prefix  function  Not_Equals.  Finally,  it  is  reason¬ 
able  to  assume  that  the  most  frequently  used  function  to  cast  a  value  of  type 
Boolean_with_Unknown  to  type  Boolean  is  the  ls_True  function  used  in  the  prior  example. 
Indeed,  the  semantics  of  the  SQL  where  clause  are  precisely  evaluation  using  the  rules  of 
Section  3.1 .2  followed  by  an  application  of  ls_True. 
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For  the  reasons  given  in  the  prior  paragraph,  sets  of  overloadings  of  the  comparison 
operators  are  defined  in  the  support  packages  on  the  null  bearing  _Type  types.  These  over- 
loadings  return  Boolean,  not  Boolean_with_Unknown  as  the  operators  of  Section  3.1.2. 
These  overloadings  are  defined  as  follows:  for  the  operator  "op,"  and  objects  O.,  and  02  of 
a  null  bearing  _Type  type,  the  Boolean-valued  expression 

Oj.  °p  °2 

is  defined  as 

Im_7cu*(01  op  02) 

where  in  the  second  expression,  "op"  is  the  overloading  which  returns 
Boolean_with_Unknown.  (If  "op"  is  "="  or  7=",  the  second  expression  is  written  in  prefix 
notation,  using  Equals  or  Not_Equals,  respectively.)  If  P  is  any  Boolean  combination  of  com¬ 
parisons  from  this  section,  and  P'  is  the  result  of  substituting  the  three-valued  operators  from 
Section  3.1.2  into  P,  then  the  value  of  P  is  ls_True(P’). 

Example 

The  running  example  of  this  section  can  also  be  coded  as 

If  City  =  Wi.fch_Null("Pi.tt«burgh")  or  else 

Quantity  >  With_Nu.ll  (1000)  then 
Countar  :=  Countar  +  1; 

If  Not_Null  (Quantity)  then 

aaaign (Sum_Quantity,  Quantity  +  Sum_Quantity) ; 

end  If; 

end  if; 

A  Note  on  Type  Ambiguities 

Notice  that  the  context  determines  whether  a  given  operator  is  three-valued  or  Boolean 
valued.  If  the  predicate  P  does  not  contain  the  equality  operator,  then  the  predicate  P'  as 
defined  above  is  syntactically  identical  to  P.  The  context  must  be  sufficient  to  determine 
which  interpretation  is  meant.  For  example,  the  context  ls_True(.)  is  sufficient  to  determine 
that  the  three-valued  interpretation  is  required  for  P’  in  ls_True(P’).  Similarly,  the  context  of 
P  in  If  P  then  ...  end  if;  is  sufficient  to  determine  that  P  is  Boolean  valued.  Consider  the 
expression  01  >  02,  which  has  both  a  three-valued  and  Boolean  interpretation.  The  case 
statements 

case  Boolean'  (Ox  >  02)  Is 
when  TRUE  =>  ...  ; 
when  false  => 
end  case; 

case  Bool«an_with_UrJcnown '  (02  >  02)  is 
when  TRUE  =>  ...  ; 
when  false  => 
when  unknown  => 
end  case; 

would  not  compile  were  the  type  qualifications  not  present.  As  written,  these  statements  will 
perform  as  expected. 


CMU/SEI-89-TR-1 6 


27 


The  presence  of  an  equality  operator  or  a  Boolean  short  circuit  control  form  within  a  predi¬ 
cate  is  sufficient  tc  determine  its  type.  Therefore  the  predicate 

Equal*  (Oj,  02)  or  Ox  >  02 

is  unambiguously  of  type  Boolean_with_Unknown  and  the  expression 
Oj  =  o2  or  o2  >  o2 

is  unambiguously  of  type  Boolean;  whereas  the  expression 
°1  >=  °2 

is  ambiguous.  Similarly,  the  expression 
(o^  >=  o2)  or  (ox  >=  o3) 

is  ambiguous,  but  the  expression  (01  >=  02)  or  else  (01  >=  03)  is  unambiguously  of  type 
Boolean. 

A  Note  on  Logic 

The  Boolean-valued  comparison  operators  discussed  in  this  section  do  not  obey  all  the  nor¬ 
mal  rules  of  propositional  logic.  Furthermore,  due  to  the  definition  of  Ada,  their  behavior  is 
inconsistent.  The  problem  arises  in  the  so-called  rule  of  double  negation. 

Again,  let  P  be  any  predicate  formed  using  the  Boolean  operators  and  and  or  from  Boolean¬ 
valued  expressions.  Now  let  P'  represent  the  result  of  performing  the  following  substitutions 
toP:15 

•  each  comparison  operator  is  replaced  by  its  negation;  that  is,  =  is  replace  by  /=, 

<  is  replaced  by  >=,  etc. 

•  and  is  replaced  by  or 

•  or  is  replaced  by  and 

This  substitution  produces  the  result  of  taking  the  expression  not  P  and  distributing  the  ne¬ 
gation  over  the  other  operators.  The  rule  of  double  negation  states  that  the  equality 
p  ■  not  P' 

is  valid,  that  is,  always  holds.  This  rule  does  not  apply  to  predicates  formed  from  the 
Boolean-valued  comparison  operators  of  this  section.16  This  fact  can  be  used  to  advantage. 
For  example,  in  the  statement 

If  Quantity  >  With_Null(1000)  then 
end  If; 

the  sequence  of  statement  in  the  then  clause  are  executed  only  for  non-null  quantities  in 
excess  of  one  thousand.  In  contrast,  the  statements  in  the  then  clause  of 

If  not  Quantity  <=  With_Null  (1000)  then 
end  if; 


15The  Boolean  operators  not  and  xor  have  been  omitted  to  simplify  the  substitution.  Given  that  the  negation  of 
every  comparison  operator  is  a  comparison  operator,  as  in  the  first  bullet  item,  any  predicate  using  not  and  xor 
can  be  recoded  as  one  using  and  and  or  exclusively. 

16The  law  of  double  negation  is  usually  stated  as  the  equality  P  -  not  (not  P)  This  law  goes  hold  to  predicates 
formed  from  the  operators  of  this  section. 
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will  be  executed  for  those  quantities  and  also  for  all  null  quantities.  Recall  that  the  null  value 
in  SQL  represents  missing  information.  The  null  Quantity  represents  a  fixed  but  unknown 
value  for  Quantity  which  may  exceed  one  thousand.  Thus  the  second  if  statement,  which  is 
often  called  the  maximal  solution,  executes  the  sequence  of  statements  in  the  then  clause 
for  any  quantity  which  might  fit  the  predicate,  while  the  first  statement,  the  minimal  solution, 
executes  that  sequence  only  for  quantities  which  necessarily  do  fit  the  predicate. 

Regrettably,  this  behavior  is  not  consistent.  The  inconsistency  stems  from  the  fact  that  Ada 
does  not  allow  an  overloading  of  the  inequality  operator  7=“  to  be  independently  defined. 
Rather,  7=M  is  implicitly  defined  to  be  the  complement  of  In  short,  the  equivalence 
(ox  =  o2>  =  not  (ox  /=  o2) 

is  valid.  When  a  complex  predicate  contains  both  “=”  (or  7 =")  and  other  comparison 
operators,  the  result  of  the  double  negation  process  outlined  above  is  difficult  to  predict.  In 
such  cases  it  is  best  to  use  the  three-valued  operators  and  the  case  statement.  Thus  the 
maximal  solution  to  the  running  example  of  these  sections  can  be  written  as 

case  Boolean  with  Onknown' ( 

Equal* (City,  With_Null ("Pittsburgh") ) 
or 

Quantity  >  With_Null (1000) )  Is 
When  TRUE  |  ONKNOWN  =>  <a*  ba£ora> 

when  FALSE  =>  null; 
end  case; 

The  extended  example  in  Chapter  8  contains  further  discussion  of  these  details. 


3.2.  The  Image  and  Value  Functions 

In  addition  to  the  testing,  conversion,  comparison,  and  arithmetic  functions  types  and  as¬ 
signment  procedure,  the  SAME  support  for  integer  in  the  packages  SQL_lnt_Pkg  and 
SQL_Smallint_Pkg  includes  the  functions  Image  and  Value.  These  functions  are  seman¬ 
tically  identical  to  the  Ada  attribute  functions  ’Image  and  ’Value  except  that  they  operate  on 
character  strings  of  type  SQL_Char  (or  SQL_Char_Not_Null)  rather  than  the  predefined  type 
string.  This  allows  character  set  independent  programs  to  be  written,  as  strings  of  these 
types  are  always  over  the  machine’s  native  character  set.  When  used  with  objects  of  some 
_Not_Null  type,  these  functions  take  or  return  strings  of  type  SQl_Char_Not_Null;  when 
used  with  an  object  of  a  null  bearing  _Type  type,  they  take  or  return  SQL_Char  strings,  with 
the  null  value  of  the  source  type  being  transformed  into  the  null  value  of  the  target  type. 
Notice  that  the  character  string  operands  of  these  functions  are  of  the  base  types  declared 
in  SQL_Char_Pkg.  Application  programs  do  not  have  visibility  to  that  package.  A  means  of 
getting  visibility  to  the  base  types  is  given  in  Section  3.8. 
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3.3.  Range  Constraints  and  the  Generic  Sub-Packages 

Many  relational  database  management  systems  provide  for  data  integrity  constraints.17 
Among  these  there  is  usually  the  ability  to  apply  range  constraints  to  numeric  columns.  The 
SAME  extends  this  ability  to  Ada  program  variables  holding  database  values. 

Example 

Suppose  all  status  values  must  be  positive.  In  that  case,  the  definitions  of  the  abstract 
Status  domain  would  be 

type  St«tu*_Not_Null  is  new  SQL_Int_Not_Null 
range  l  ..  SQL_int_Not_Null ' last,- 
type  Statu*_Typ«  is  new  SQL_Int ; 
package  st*tu»_o pa  is  new 

SQL_Int_Op» (Statu«_Typ« ,  Statu«_Not_Null) ; 


Notice  that  the  range  constraint  is  applied  to  _Not_Null  type  only.  Status_Type  is  a  limited 
private  record  type,  to  which  range  constraints  cannot  be  applied.  The  generic  instantiation 
Status_Ops  creates  an  Assign  procedure  which  will  enforce  the  range  constraint  on  objects 
of  Status_Type. 

The  specification  of  the  package  SQL_lnt_Ops,  which  appears  within  the  specification  of  the 
package  SQL_lnt_Pkg,  is  given  in  Figure  3-2.  The  packages  SQL_Smallint_Ops, 
SQL_Real_Ops  and  SQL_Double_PrecisionjDps  are  identical  to  SQL_lnt_Ops,  with  the  ob¬ 
vious  modifications.  SQL_Char_Ops  is  slightly  different  and  is  described  in  Section  3.4. 

Notice  that  the  generic  takes  two  formal  parameters  which  are  types  and  three  which  are 
subprograms.  The  subprograms  will  default  to  subprograms  with  the  appropriate  names  and 
profiles,  which  are  derived  by  the  type  derivation.  (The  packages  should  be  instantiated  in 
the  declarative  region  in  which  the  derived  types  are  declared.  See  Section  3.7.)  Therefore, 
when  instantiating  these  packages,  only  the  types  should  be  passed  as  actuals. 

Notice  that  the  generic  subpackage  generates  three  subprograms  which  provide  conversion 
and  assignment  procedures.  It  is  not  necessary  to  generate  the  arithmetic  and  comparison 
operators.  They  are  derived  with  the  derivation  of  the  type  Status_Type. 

The  procedure  Assign  produced  by  the  generic  instantiation  implements  range  constrained 
assignment  for  the  limited  private  types.  It  does  this  by  calling  the  procedure 
Assign_With_Check18  and  passing  it  the  values  of  the  attributes  ’FIRST  and  ’LAST  from  the 
_Not_Null  type.  See  the  appendix  for  the  complete  code. 

Note:  The  implementation  of  range  constraints  by  the  SAME  standard  packages  is  meant  to 
support  the  implementation  of  range  constraints  by  the  DBMS.  As  this  feature  is  missing 
from  the  current  SQL  standard,  a  given  DBMS  may  not  support  it.  This  does  not  mean  that 
range  constraints  cannot  be  used  in  Ada  applications  employing  the  SAME.  The  constraint 


17These  constraints  do  not  appear  in  the  current  ANSI  standard  [2]  but  do  appear  in  *he  follow-on  standard  in 
development  [4], 

10This  procedure  is  not  meant  to  be  called  directly  by  application  programs.  Applications  should  use  only  the 
Assign  function  produced  by  the  generic  instantiation. 
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generic 

type  With_Null_Typ«  is  limited  private ; 

--  derived  from  Sql  Int 
type  without_Null_Type  is  range  <>; 

--  derived  from  Sql_Int_Not_Null; 

--  for  floating  point  typea 
--  range  is  replaced  with  digits 

With  function  With_Null_Base  (Value  :  Sql_Int_Not_Null) 
return  With_Null_Type  is  <>; 

With  function  Without_Null_Ba#e  (Value  :  With_Null_Type) 
return  Sqi_int_Not_Null  Is  <>; 

With  procedure  A#«ign_With_Check  ( 

Left  :  in  out  With_Null_Type;  Right  :  With_Null_Type; 

First,  Last  :  Sql_Int_Not  Null)  is  O ; 

—  subprograms  with  the  above  names 
--  appear  in  Sql_Int_Pkg  specification 

package  Sql_lnt_Op#  is 

function  With_Null  (Value  :  Without_Null_Type) 
return  With_Null_Type; 

function  Without_Null  (Value  ;  With_Null  Type) 
return  Without_Null  Type; 
procedure  Assign  (Left  ;  inout  With_Null_Type ; 

Right  :  With_Null_Type) ; 

end  Sql_Int_Opa; 

Figure  3-2:  The  Generic  Subpackage  Sql_lnt_Ops 

“all  status  values  are  positive,"  if  applied  in  the  SAME  abstract  domain  definitions  as  de¬ 
scribed  above,  should  represent  a  constraint  on  the  real  world.  If  this  constraint  is  true  of  the 
real  world,  then  any  non-positive  value  of  Status  is  invalid  and  represents  a  corruption  of  the 
database.  If  this  constraint  is  not  supported  by  the  DBMS,  the  exception  Constraint_Error 
will  be  raised  when  this  database  corruption  is  encountered.  That  may  cause  the  abnormal 
termination  of  one  database  application  due  to  the  improper  behavior  of  a  different  appli¬ 
cation,  that  application  which  inserted  the  invalid  data.  The  incorrect  application  could  not 
have  been  written  in  Ada  using  the  SAME. 

The  conversion  functions  With_Null  and  Without_Null  are  also  generated  by  the  _Ops 
generic  subpackages.  These  functions  convert  between  the  two  types  making  up  an  ab¬ 
stract  domain.  Ada  subprogram  derivation  rules  will  not  generate  functions  with  these 
parameter  profiles. 

The  _Ops  generic  subpackages  were  designed  to  reduce  compile-time  and  runtime  space 
utilization.  Only  those  subprograms  that  could  not  be  derived  using  Ada  subprogram  deriva¬ 
tion  rules  are  instantiated  using  generic  instantiation. 

A  Note  on  Type  Derivation  and  Subtyping 

The  abstract  domains  defining  the  database  in  Ada  can  be  arranged  into  type  and  subtype 
hierarchies  in  the  usual  way.  For  example,  suppose  it  is  desirable  to  define  preferred  sup¬ 
pliers  as  those  suppliers  having  a  status  greater  than  100.  This  can  be  captured  in  subtype 
declarations  as  follows. 

Sllbtype  Preferred  St»tue_Not_Null 

Is  statu«_Not_Null  range  101  ..  statu«_Not_Null' last,- 
subtype  Preferred_Statu#  Type  is  Stetue  Type; 
package  Preferred_Statu#_Op#  is  new  SQL  Int  Op# 

(Preferred  St»tu«_Type,  Preferred  Statu#  Not  Null); 
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However,  care  must  be  exercised  in  naming  the  subprograms  operating  on  variables  of  the 
subtype.  The  subprograms  generated  in  the  package  Preferred_Status_Ops  have  the  same 
parameter  profiles  as  those  generated  in  the  package  Status_Ops  defined  in  Figure  1  -7. 
This  is  because  parameter  profiles  depend  only  on  base  types,  not  on  subtypes.  Consider 
the  following  program  fragment. 

Pr«f«rr«d_Stafcu«_Variabl«  :  Pr«£arrad_Stat,u«_Type; 
begin 

St«tu»_Op»  .  assign  (Prsf  srrsd_Status_Vs_riS±>ls , 

St*tus_Ops  ,wi'th_Null  (1) )  ; 


and; 

This  will  execute  without  raising  an  exception  and  will  result  in  the  variable's  having  a  value 
out  of  range.  Further,  the  subprogram  declarations  in  the  packages  Status_Ops  and 
Preferred_Status_Ops  hide  each  other,  if  both  are  brought  into  scope  with  use  clauses. 

Warning:  Since  range  constraint  checking  of  objects  of  the  null  bearing  _Type  types  is 
done  by  the  generated  Assign  procedures  and  not  directly  by  the  compiler,  these  constraints 
do  not  behave  exactly  like  Ada  constraints.  In  particular,  if  an  arithmetic  expression  resulting 
in  a  _Type  object  is  passed  as  an  actual  parameter  to  a  procedure,  it  will  not  be  range 
constrained  and  may  not  satisfy  the  range  constraint.  For  safety,  assign  the  expression  to  a 
temporary  variable  of  the  _Type  and  pass  the  temporary  as  the  actual. 


3.4.  Character  Data 

The  SAME  treatment  of  character  string  data  is  similar  to  its  treatment  of  integer  and  floating 
point  data.  Each  abstract  character  string  domain  is  represented  by  two  type  declarations. 
One  of  the  types  is  a  visible  Ada  type;  the  other  is  a  limited  private  type  with  operations 
defined  on  it  that  simulate  the  corresponding  SQL  operations.  Character  string  variables  and 
database  columns  do  not  have  associated  range  constraints,  but  they  do  have  lengths.  The 
length  of  an  SQL  character  string  column  is  part  of  its  definition.  Abstract  domain  definitions 
for  character  string  domains  also  contain  a  length. 

The  SQL  semantics  of  character  data  include  the  semantics  of  the  null  value  for  strings19  as 
described  in  Section  3.1.2.  Unlike  the  case  of  integer  and  floating  point  data,  for  which 
operations  on  non-null  values  have  the  same  effect  in  Ada  and  SQL,  SQL’s  definition  of 
assignment  and  comparison  for  character  strings  differs  from  Ada’s  definition.  For  example, 
when  comparing  two  strings,  SQL  pads  the  shorter  string  with  blanks  (Database 
Language-SQL,  paragraph  5.1 1.5  [2]). 

The  comparison  of  two  character  strings  is  determined  by  the  comparison  of 
<character>s  with  the  same  ordinal  position.  If  the  strings  do  not  have  the  same 
length,  then  the  comparison  is  made  with  a  working  copy  of  the  shorter  string  that 
has  been  effectively  extended  on  the  right  with  <space>s  so  that  it  has  the  same 
length  as  the  other  string. 


19The  null  string  value  is  distinct  from  the  null  string,  i.e.,  the  string  of  length  0. 
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Very  similar  behavior  governs  the  assignment  of  character  strings  to  database  columns  in 
SQL  insert  and  update  commands  (cf.  Database  Language — SQL,  general  rule  7.b  of  Sec¬ 
tions  8.7,  8.11  and  8.12  [2]). 

The  SAME  standard  package  SQL_Char_Pkg  defines  the  the  type  SQL_Char_Not_Null  as 
a  derived  type  of  SQL_Standard.Char  (see  Figure  2-2)  with  no  added  constraints. 
SQL_Char_Not_Null  is  therefore  an  unconstrained  one  dimensional  array  whose  component 
type  is  specified  when  sql_standard  is  compiled.  SQL_Char_Pkg  also  declares  a  limited 
private,  discriminated  record  type  SQL_Char  and  comparison  and  assignment  operations  on 
that  type  which  simulate  the  SQL  operations.  The  discriminant  is  named  Length  and  is  of 
type  SQL_Char_Length,  a  subtype  of  INTEGER  declared  in  SQL_Char_Pkg.  The  dis¬ 
criminant  value  is  used  to  specify  the  character  string  length. 

SQL_Char_Pkg  also  contains  a  generic  subpackage,  SQL_Char_Ops.  As  before,  it 
generates  conversion  functions  between  a  type  derived  from  SQL_Char_Not_Null  type  and 
a  type  derived  from  SQL_Char.  Together  the  two  type  definitions  make  up  the  abstract 
domain  definition.  (There  is  no  need  for  the  generic  subpackage  to  create  an  Assign  proce¬ 
dure.  The  version  derived  by  the  derived  type  declaration  will  suffice.)  Notice,  however,  that 
the  _Not_Null  type  is  not  the  Ada  predefined  type,  string.  Rather,  the  _Not_Null  type  is  a 
derived  type  of  SQL_Char_Not_Null,  itself  a  derived  type  of  SQL_Standard.Char.  That  type 
may  or  may  not  be  a  renaming  of  the  predefined  type  string  (that  is,  Standard. string),  as  the 
DBMS  character  set  may  or  may  not  be  ASCII.  SQL_Char_Pkg  exports  functions  which 
convert  between  each  of  the  _Not_Null  and  the  limited  private  type  and  the  predefined  type 
string.  These  functions  will  perform  character  set  conversions  if  necessary.  (The  identity  of 
the  character  set  conversion  function  is  set  during  SAME  installation.  See  the  installation 
guide  [14]  for  more  details.) 

The  remainder  of  this  section  is  as  follows.  The  generic  subpackage  is  displayed  and  ex¬ 
plained.  Abstract  domain  definitions  for  character  data,  which  differ  slightly  from  the  integer 
and  floating  point  case,  are  then  described  and  explained.  The  functions  which  convert  to 
and  from  the  predefined  string  type  are  then  explained.  Finally,  a  function  for  extracting  sub¬ 
strings  from  character  strings  of  the  limited  private  type  and  an  operator  for  concatenating 
two  such  strings  are  described. 

The  specification  of  the  generic  subpackage  SQL_Char_Ops  appears  in  Figure  3-3.  This 
generic  subpackage  is  to  be  instantiated  in  the  same  manner  as  the  integer  and  floating 
point  subpackages:  only  the  types  are  passed  as  actuals,  the  formal  subprograms  are 
meant  to  default. 

The  functions  With_Null  and  Without_Null  generated  by  instantiation  of  this  package  have 
the  same  intended  meaning  as  before:  to  convert  between  the  two  types  of  an  abstract 
domain.  The  function  Without_Null_Unpadded  returns  the  value  of  its  input  with  trailing 
blanks  removed;  the  last  character  in  the  result  of  this  function  is  never  blank.  If  the  input 
string  is  all  blank,  the  output  is  an  array  of  length  zero.  SQL_Char_Pkg  exports  the  function 
Unpadded_Length  with  operand  SQL_Char  and  result  type  SQL_Unpadded_Length,  a  sub- 
type  of  NATURAL.  The  defining  property  of  the  function  is 
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generic 

type  with_Null_Type  is  limited  private 
--  derived  from  SQL_Char 

type  Without_Null_Type  is  array  (poaitiv*  range  <» 

Of  sol_st*»h*j(o  .  Characrter_Type ; 

—  derived  from  SQL_Cha_r_Not_Nu.ll 

with  function  With_Null_B«»e  (Value:  SQL_Char_Not_Null) 
return  With_Null_Type  is  <>; 

With  function  Without_Null  But  (Value:  With_Null_Type) 
return  SQL_Char_Not_Null  is  O; 

With  function  Without  Null_Onpadded_Baee  (Value:  With  Null_Type) 
return  SQL_CharJSot_Null  is  <>; 
package  SQL_Cher_Opa  Is 

function  Witb_Null  (Value  :  Without_Null_Type) 
return  With_Null_Type; 

.-..-l.’on  Witho— _Null  (Value  Wj.ch_Null_iype) 
return  Without_Null_Type; 

function  Without_Null_Unpadded  (Value  With_Null  Type) 
return  Without_Null  Type; 
end  S QL_Cha r_Op * ; 

Figure  3-3:  The  Generic  Subpackage  SQL_Char_Ops 
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Without_Null_Onp»dd«d (x) ' LENGTH  =  Onpadd«d_L«ngth (x) 

Notice  that  (assuming  xis  not  the  null  value) 

Witliout._Null  (x)  '  LENGTH  =  x. LENGTH 

It  should  be  noted  that  Without_Nu!l,  Without_Null_Unpadded,  and  Unpadded_Length  raise 
Null_Value_Error  when  given  the  null  value  ao  input. 

The  generic  SQL_Char_Ops  explains  to  some  extent  the  structure  of  abstract  domain  defini¬ 
tions  for  character  data.  A  character  string  abstract  domain  definition  contain*  two  type 
declarations  and  two  subtype  declarations,  along  with  the  instantiation  of  the  generic  sub¬ 
package.  The  following  declaration  of  the  abstract  domain  PNO  is  copied  from  Figure  1  -7. 

type  PNONN_B*««  is  new  SQL_Cii*r_P)cg.  SQL_Ch*r_Not_Null; 
subtyf-  rs»_"©tj3rll  Is  r::ONN_Ba«-  (1..5); 
type  PNO_B»««  is  new  SQL_Ch*r_P)cg .  SQL_Chax; 
subtype  PNO_Typ«  Is  PNO_Ba«*  (PNO_Not_Null' Length) ; 
package  PNO_op«  is  new 

SQL_Ch*r_Pkg.SQL_Cli*r_Op« (PNO_Ba««,  PNONN_Bae«) ; 

The  type  definitions,  whose  type  names  have  the  suffix  __Base,  declare  unconstrained  types. 
The  subtypes  complete  the  domain  definition  by  supplying  the  string  length.  The  subtype 
declarations  are  to  be  used  in  declaring  variables  of  the  abstract  domain.  Thus  the  subtype 
declarations  have  the  suffixes  _Not_Nu!l  and  _Type  as  appropriate. 

The  pattern  of  the  above  example  should  always  be  followed  in  the  definition  of  character 
string  abstract  domains.  The  length  of  the  character  strings  as  they  are  stored  in  the  data¬ 
base  should  be  encoded  as  an  index  constraint  on  the  _Not_Null  subtype.  The  value  of  the 
discriminant  in  the  definition  of  the  _Type  subtype  is  the  Length  attribute  value  of  the 
_Not_Null  subtype.  This  pattern  guarantees  that  the  _Type  and  _Not_Null  subtypes  are  con¬ 
sistent. 

The  formal  type  parameter  Without_Null_Type  of  the  generic  package  SQL_Char__Ops  (see 
Figure  3-3),  is  an  unconstrained  array  type.  Therefore,  the  actual  type  parameter  must  also 
be  unconstrained  (see  LRM[  15]  12.3.4(2}).  This  explains  the  division  of  the  declaration  of 
the  _Not_Null  type  into  two  pieces.  Notice  that,  as  the  unconstrained  types  are  passed  to 
the  generic  instantiation,  the  functions  it  generates  return  objects  of  the  unconstrained 
types.  This  is  particularly  important  in  the  case  of  Without_Nul!_Unpadded,  which  returns 
objects  whose  length  cannot  be  determined  at  compile  time.  These  objects  may  not  meet 
the  _Not_Null  subtype  constraint,  but  they  are  valid  objects  of  the  _Base  type.  (Similar  state¬ 
ments  apply  to  the  substring  function  described  below.) 

The  functions  To_SQL_Char  and  To_SQL_Char_Not_Null,  exported  by  the  SQL_Char_Pkg, 
take  an  operand  of  the  predefined  type  string  and  return  a  value  of  either  the  limited  private 
type  SQL_Char  or  the  one  dimensional  array  type  SQL_Char_Not_Null  (or  types  making  up 
an  abstract  domain  definition  derived  from  these).  The  length  of  the  result  is  the  length  of 
the  input.  Both  functions  raise  Constraint_Error  if  the  input  is  the  string  of  length  zero. 

There  are  two  versions  of  the  function  To_String  and  To_Unpadded_String,  one  taking  ob¬ 
jects  of  type  SQL_Char_Not_Nul!  and  one  taking  objects  of  type  SQL_Char  (or  types  de 
rived  from  these).  As  was  the  case  for  Without_Null  and  Without_Null_Unpadded,  the  fol¬ 
lowing  identities  hold  (assuming  x  is  of  a  child  type  of  SQL_Char  and  is  not  null) 
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To_String(x)  'LENGTH  =  x.Langth 

To  Onpadded  String (x) ' LENGTH  =  Onpaddad_Lar>gth  (x) 

and  (assuming  xis  of  a  child  type  of  SQL_Char_Not_Null) 

To_String(x) 'LENGTH  =  x' Langth 

There  is  no  predefined  technique  for  determining  the  length  of  To_Unpadded_String(x)  if  x  is 
of  a  child  type  of  SQL_Char_Not_Null. 

It  is  impossible  to  reproduce  exactly  the  syntax  of  the  Ada  slice  for  extracting  substrings  of 
SQL  strings  (strings  which  are  objects  of  the  type  SQL_Char  or  a  type  derived  from  it). 
Therefore,  there  exists  a  function  substring  in  SQL_Char_Pkg  which  simulates  the  substring 
function  of  the  follow-on  version  of  the  SQL  standard,  SQL2  [4],  in  preparation.  Its  definition 
i<? 

function  substring  (Valua  :  SQL_Char ; 

Start,  Langth  :  SQL_Chax_Langth)  return  SQL_Char; 

where  substnng(str,  k,  m)  evaluates  to  the  substring  of  str  starting  at  the  k*h  ordinal  position 
(relative  to  1)  and  containing  m  characters,  unless  (i)  str  is  null,  in  which  case  substring(str, 
k,  m)  is  also  null;  or  (ii)  k<=Oor  m<-Oor  k+m-1  >str.LENGTH in  which  case  substringfstr,  k, 
m)  causes  Constraint_Error  to  be  raised. 

SQL_Char_Pkg  also  exports  a  concatenation  operator,  tor  3Gt__Char.  Its  definition  is 

function  "fi"  (Laft,  Right  :  SQL_Char)  raturn  SQL_Char; 

If  either  operand  of  "&"  is  null,  the  result  is  null;  otherwise,  the  result  has  length 
Left.LENGTH  +  Right.LENGTH. 
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3.5.  Decimal  Fixed  Point  Arithmetic 


Among  the  data  types  recognized  by  ANSI  SQL  is  the  type  Decimal.  Like  most  of  the  SQL 
data  types,  the  decimal  type  is  oriented  to  a  concrete,  hardware  representation.  Although 
there  is  nothing  in  the  standard  that  requires  it,  any  DBMS  which  supports  the  Decimal  type 
is  likely  to  do  so  by  storing  values  of  the  type  in  the  machine's  packed  or  binary  coded 
decimal  (BCD)  representation.  This  section  describes  the  support  software  provided  h.-  the 
SAME  for  numeric  data  coded  in  BCD. 

It  should  be  noted  immediately  that  ANSI  standard  SQL  as  described  in  [2],  [4],  and 
[1 6]  does  not  support  decimal  data  in  Ada  programs.  Therefore,  this  section  describes 
SAME  functionality  outside  of  standard  SQL.  It  may  be  that  future  versions  of  the  ANSI  stan¬ 
dard  will  correct  this  deficiency  in  a  manner  that  is  not  compatible  with  the  software 
presented  in  this  section.  It  is  to  be  hoped  that  the  transition  to  any  such  future  standard  will 
be  relatively  easy. 

It  is  possible  to  read  or  write  database  values  stored  in  decimal  without  any  support  for  the 
type  in  Ada  by  taking  advantage  of  SQL’s  weak  typing.  If,  within  an  SQL  statement,  a 
decimal  value  is  stored  into  or  read  from  a  parameter  of  some  other  numeric  type  (such  as 
Real  or  Int),  SQL  will  perform  the  necessary  conversion  automatically.  The  disadvantages  of 
this  approach  are  the  time  taken  to  do  the  conversion  and  the  loss  of  accuracy  as  a  result  of 
the  conversion.  Decimal  fractions  cannot  in  general  be  accurately  represented  in  binary 
notation.  Furthermore,  decimal  representations  generally  allow  for  more  digits  of  precision 
than  do  binary  integer  or  floating  representations.  It  is,  as  always,  up  to  the  application’s 
designers  and  engineers  to  determine  the  best  strategy  for  decimal  quantities.  The  form  of 
the  support  for  BCD  in  the  SAME  is  that  of  an  abstract  data  type  whose  fundamental  opera¬ 
tions  (arithmetic,  comparison,  etc.)  are  provided  by  assembler-ievei  routines.  It  should  be 
noted  that  this  software  is  very  inefficient  in  comparison  to  the  software  that  might  be  pro¬ 
duced  directly  by  a  compiler  which  supported  BCD.  As  there  are  no  such  compilers  at  this 
time,20  the  software  presented  here  will  at  least  allow  Ada  programs  access  to  BCD  coded 
data. 

The  package  SQL_Decimal_Pkg  provides  basic  support  for  a  non-null  bearing  and  a  null 
bearing  type.  The  package  defines  an  Ada  type  for  BCD  objects  and  arithmetic  and  com¬ 
parison  operators  for  that  type.  It  then  builds  on  that  concrete  type  to  provide  the  null  bear¬ 
ing  type  with  its  associated  operators. 


^No  modification  to  the  Ada  language  is  needed  to  support  BCD.  All  that  is  needed  is  an  implementation  of  a 
pragma  Decimal,  which  instructs  the  compiler  to  represent  values  of  its  (fixed  point  type)  operand  in  BCD. 
Compilers  are  free  to  add  such  pragmas  (LRM 2.8(8)). 
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3.5.1.  Basic  Support 

The  package  SQL_Decimal_Pkg  provides  the  Ada  programmer  access  to  the  machine's 
BCD  representation  and  instruction  set.  All  of  the  basic  operations  provided  by  this  pack¬ 
age,  arithmetic,  comparison  and  conversion  operators  and  functions,  are  implemented  in  as¬ 
sembler.  Sample  implementations  for  the  VAX  and  IBM  360/370  instruction  sets  can  be 
found  in  Appendix  C.21 

All  of  the  operations  are  done  with  the  maximum  precision  possible  on  the  target  hardware. 
The  constant  MAX_DIGITS  defined  in  the  specification  of  SQL_Decimal_Pkg  is  the  number 
of  digits  in  such  a  maximum  precision  number  on  the  target  machine.  SQL_Decimal_Pkg 
defines  an  Ada  type,  SQL_Decimal_Not_Null,  for  Ada  objects  whose  contents  are  BCD 
numbers  of  maximum  precision.  The  type  is  a  limited  private  record  type  with  discriminant. 
The  component  type  of  the  record  type  is  a  fixed  length  array.  SQL_Decimal_Not_Null  is  a 
limited  type  so  as  to  prohibit  the  formation  of  aggregates  of  the  type  in  the  Ada  code.  This 
ensures  that  the  contents  of  an  object  of  the  type  are  in  valid  BCD  format. 

The  length  of  the  array  component  of  SQL_Decimal_Not_Null  is  calculated  at  compile  time. 
The  comments  within  the  private  part  of  the  specification  of  SQL_D3cimal_Pkg  explain  how 
and  why  the  calculation  is  done. 

The  discriminant  of  SQL_Decimal_Not_Null  specifies  the  number  of  scale  digits,  that  is, 
digits  assumed  to  the  right  of  the  decimal  point,  in  objects  of  the  type  (or  types  derived  from 
it).  The  Assign  procedure  justifies  its  input  value  around  the  decimal  point.  If  a  value  vl  with 
scale  (discriminant)  si  is  assigned  to  an  object  with  scale  s2,  then  the  value  vl  is  shifted  left 
(si  >s2)  or  right  (s1<s2)  as  needed.  In  the  case  of  a  right  snift,  trailing  digits  are  lost  and  the 
result  is  rounded.  In  the  case  of  a  left  shift,  trailing  zeroes  are  supplied.  If  significant  high 
order  digits  would  be  lost  by  a  left  shift,  the  exception  Constraint_Error  is  raised. 

The  scale  of  the  resutt  of  an  arithmetic  operator  can  be  calculated  as  follows.  For  the  ad¬ 
ditive  operators  (+,  -)  the  result  scale  is  the  larger  of  the  input  scales.  (Justification  is  per¬ 
formed  automatically  by  the  additive  operators.)  The  result  of  a  multiplication  has  scale 
which  is  the  sum  of  the  scales  of  its  operands.  The  result  of  a  division  has  the  maximum 
scale  possible  given  the  values  of  its  operands  and  the  nature  of  the  hardware  decimal  di¬ 
vide  instruction.22  All  four  of  the  arithmetic  operators  raise  Constraint_Error  if  the  result  has 
more  significant  digits  to  the  left  of  the  decimal  point  than  can  be  accommodated.  These 
definitions  of  arithmetic  are  modeled  after  the  treatment  given  to  decimal  arithmetic  by  SQL 
[2]. 

Other  noteworthy  features  of  SQL_Decimal_Pkg  appear  in  the  following  list.  They  are  de¬ 
scribed  with  respect  to  the  non-null  bearing  type  SQL_Decimal_Not_Null.  The  next  subsec¬ 
tion  describes  the  support  for  the  null  bearing  type. 


21  These  implementations  are  reentrant.  Therefore,  they  are  safe  for  use  within  Ada  multi-tasking  programs  or 
other  environments  in  which  reentrancy  is  a  requirement. 

22The  VAX  decimal  divide  instruction  performs  integer  division  on  its  operands  and  returns  the  quotient  with 
the  full  width,  i.e.,  precision,  of  the  dividend.  The  IBM  decimal  divide  also  does  integer  division  but  returns  a 
quotient  and  a  remainder  in  the  location  of  the  dividend.  Therefore  a  division  which  operates  successfully  on  the 
VAX  may  raise  Constraint_Error  on  an  IBM  machine. 
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•  The  parameterless  functions  Zero  and  One  return  the  appropriate  decimal  con¬ 
stants. 

•  The  function  Shift  performs  multiplications  by  powers  of  ten.  A  positive  value  k 
for  the  Scale  operand  of  Shift  results  in  a  left  shift  by  k  digit  positions  (an  effec¬ 
tive  multiplication  by  10k);  a  negative  value  results  in  a  right  shm  Dy  k  digit  posi¬ 
tions  (an  effective  multiplication  by  10'k).  Constraint_Error  is  raised  if  a  loss  of 
significance  would  result  from  a  left  shift.  Right  shifts  always  succeed. 

•  There  is  a  rich  collection  of  functions  for  converting  numeric  values  between 
decimal  and  other  representations.  All  of  the  other  database  domain  classes, 
except  for  Real  and  Smallint  but  including  database  character  strings,  can  be 
interconverted  with  decimal  representations  (subject,  of  course,  to  constraints). 
There  is  also  a  function  to  convert  to  the  type  Standard. String,  but  none  to  con¬ 
vert  from  Standard. String.  To  convert  a  Standard. String  object  to  decimal,  first 
convert  it  to  SQL_Char_Not_  Null. 

The  reasoning  behind  this  selection  of  types  for  interconversion  of  decimal  data 
is  as  follows.  Conversion  between  other  numeric  and  character  types  can  be 
accomplished  through  Ada  explicit  type  conversions  and  the  Image  and  Value 
functions  and  predefined  attributes  for  the  integer  types.  The  predefined  func¬ 
tions  do  not  exist  for  interconversion  with  decimal  data,  and  must  be  created. 
The  inclusion  of  SQLJnt_Not_Null  in  the  set  of  types  for  which  conversion 
functions  exist  and  the  exclusion  of  SQL_Smallint_Not_Null  and 
Standard. Integer  (and  the  similar  choices  with  respect  to  the  floating  point  and 
character  string  types)  from  that  set  is  a  consequence  of  the  rules  of  Ada  im¬ 
plicit  type  conversions  (see  LRM  4.6(15)).  Consider  the  expression 
To_SQL_Decimal_Nct_Null(1).  The  literal  f  has  type  <universal  integer>.  It 
must  be  converted,  implicitly,  to  a  type  for  which  Tc_SQL_Decimal_Not_Null  is 
defined.  Were  there  more  than  one  such  integer  type,  the  implicit  conversion 
would  be  ambiguous  and  could  not  proceed.  It  would  be  necessary  to  write 
To_SQL_Decimal_Not_Null(  Integer  (1) ),  say.  As  it  is  assumed  that  literal 
operands  are  common  for  these  functions,  since  the  direct  formation  of  decimal 
constants  is  impossible,  the  inclusion  of  only  one  type  from  each  class  (integer, 
floating  point,  and  character  string)  makes  these  expressions  easier  to  write. 

The  conversion  functions  are  described  in  the  following  list.  Use  of  these  func¬ 
tions  will  require  type  conversions  to  or  from  SAME  base  types,  as  the  rules  of 
Ada  program  derivation  do  not  produce  functions  with  the  appropriate 
parameter  profiles.  Sections  3.8  and  5.6.2  describe  these  type  conversions. 

•  The  function  To_SQL_Char_Not_Nuli  returns  a  printable  form  of  a 
decimal  value  as  an  object  of  the  type 

SQl_Char_Pkg.SQL_Char_Not_Null.  The  function  is  modeled  after  the 
'Image  functional  attribute  and  the  Float_io  put  routines.  Leading  zeroes 
to  the  left  of  the  decimal  point  are  suppressed,  unless  all  such  digits  are 
zero,  in  which  case  a  single  zero  appears;  a  leading  position  is  reserved 
for  a  sign  character  which  is  blank  for  non-negative  values  and  for  neg¬ 
ative  values;  all  digits  to  the  right  of  the  decimal  point  appear  for  all 
values;  a  decimal  point  does  not  appear  for  integers,  i.  e.,  for  objects  with 
a  scale  of  zero. 

•  The  function  To_String  is  modeled  after  the  To_SQL_Char_Not_Null 
function,  but  returns  an  object  of  type  Standard. String. 
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•  The  functions  To_SQL_Double_Precision_!\lot_Null  and 
To_SQL_lnt_Not_Null  return  objects  of  types 
SQL_Double_Precision_Pkg.SQL_Double_Precision_Not_Nuli  and 
SQL_lnt_Pkg.SQL_lnt_Not_Null.  Conversion  to  integer  rounds  to  the 
nearest  integer;  it  raises  Constraint_Error  if  the  decimal  value  is  too  large 
in  absolute  magnitude  to  be  stored  as  an  object  of  type 
SQL_lnt_Pkg.SQL_lnt_Nlot_Null.  Conversion  to  float  truncates,  but  does 
not  raise  any  exceptions. 

•  The  function  To_SQL_Decimal_Not_Null  taking  an  operand  of  type 
SQL_Char_Pkg.SQL_Char_Not_Null  requires  its  operand  to  be  in  a  spe¬ 
cial  format.  The  first  character  must  be  either  a  blank, "+"  character,  a 
numeric  chaiacter  (i.e. ,  a  character  in  the  range  "0” ..  "9”),  a  decimal 
point  or  period  or  the  character  The  last  possibility  signifies  a 
negative  quantity;  the  remaining  possibilities  signify  a  non-negative  quan¬ 
tity.  (The  strings  "+0.0"  and  "-0.0"  are  acceptable  and  indicate  the  value 
zero.)  The  remaining  characters  must  all  be  numeric,  with  the  possible 
exception  of  a  penod.  There  can  be  no  more  than  one  period  any  where 
in  the  string,  although  there  may  be  none.  Violation  of  any  of  these 
restrictions  will  cause  Constraint_Error  to  be  raised.  The  scale  of  the 
result  is  the  number  of  characters  appearing  after  the  period,  if  present. 
Thus  the  strings  "9."  and  "9"  both  have  scale  zero,  whereas  "9.0"  has 
scale  one.  All  three  strings  represent  the  same  quantity.  This  function  is 
such  that  To_SQL_Decima!_Not_Null(  To_SQL_Char_Not_Nul!  (x)  )  =  x, 
for  x  of  the  ?Ql_Decimal_Not_Null  type. 

•  The  function  To_SQl_Decimal_Not_Null  taking  a  parameter  of  type 
SQL_lnt_Pkg.SQL_lnt_Not_Null  always  returns  an  object  of  scale  zero. 
The  equality  To_SQL_lnt_Not_Null(  To_SQL_Decimal_Not_Null  (x;  )  =  x. 
where  x  is  of  type  SQL_lnt_Pkg.SQL_lnt_Not_Null,  is  valid.  On  the  other 
hand,  the  equality  To_SQL_Decimal_Not_Null(  To_SQL_lnt_Not_Null  (xj 
)  =  x  holds  only  if  x  has  an  integral  value  and  Constraint_Error  is  not 
raised  on  the  conversion  to  integer. 

•  The  function  To_SQL_Decimjl_Not_Null  taking 
SQL_Double_Precision_Pkg.SQL_Double_Precision_Not_Nul!  raises 
Constraint_Error  if  its  input  s  too  large  in  absolute  magnitude  to  be 
represented  by  the  SQL_Decimal_Not_Null  type.  The  scale  for  inputs 
with  negative  exponents  is  calculated  as  the  exponent  of  the  input  value 
(in  Ada  normal  form.  LRM  14.3.8)  minus  the  quantity 
SQL_Double_Precision_Not_Null'Digits  - 1 .  The  scale  for  results  with 
positive  exponents  is  0.  These  conversion  functions  are  inaccurate  and 
the  equalities  To_SQL_Decimal_Not_Nul!( 
To_SQL_Double_Precision_Not_Null(  (x) )  =  x  and 
To_SQL_Double_Precision_Not_Null(  To_SQl_Decimal_Not_Null  (x)  )  = 
x  do  not  in  general  hold. 

The  function  Width  assists  in  printing  decimal  values.  The  equality  Width(x)  = 
To_SQL_Char_Not_Null(x) 'Length  is  valid. 

The  function  lntegral_Digits  (Scale)  returns  the  number  of  digits  to  t  e  left 
(right)  of  the  decimal  point  as  defined  by  the  type  of  the  operand.  These 
functions'  values  depend  only  on  the  type,  not  the  value,  of  their  operands.  The 
function  Fore  (Aft)  returns  the  number  of  significant  digits  to  the  left  (right)  of  the 
decimal  point.  These  functions  consider  leading  (trailing)  insignificant  zeroes. 
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Fore  returns  one  if  there  are  no  significant  digits  in  the  integer  portion  of  the 
input  value.  Aft  returns  one  if  there  are  no  significant  digits  in  the  fractional  por¬ 
tion.  Thus  Fore(To_Decimal_Not_Null(',0.0"))  = 
Aft(To_Decimal_Not_Null("0.0"))  =  1. 

•  The  functions  Machine_Rounds  and  Machine_Overflows  mimic  the  predefined 
Ada  floating  point  type  attributes.  They  are  both  the  constant  function  true  on 
VAX  and  IBM  machines. 


3.5.2.  SQL  Support 

The  SQL_Decimal_Pkg  defines  a  null  bearing  type,  SQL_Decimal,  in  the  usual  way.  Arith¬ 
metic  and  comparison  operators  are  defined  for  this  type  with  their  usual  semantics.  Con¬ 
version  functions  are  likewise  defined.  The  semantics  of  the  conversion  functions  are  the 
same  as  their  counterparts  defined  with  respect  to  SQL_Decimal_Not_Null  for  non-null 
values.  Conversion  functions  for  SQL_Decimal  exist  with  respect  to  all  of  the  non-null  bear¬ 
ing  types  described  in  the  list  given  above  and  also  their  null  bearing  counterparts.  For  the 
conversions  from  SQL_Decimal,  these  functions  are  distinguished  by  name.  Thus 
To_SQL_Char  as  defined  in  SQL_Decimal_Pkg  takes  an  operand  of  a  type  derived  *rom 
SQL_Decimal  and  returns  an  object  of  type  SQL_Char_Pkg.SQL_Char;  whereas 
To_SQL_Char_Not_Null  returns  an  object  of  type  SQL_Char_Pkg.SQL_Char_Not_Null. 
Symmetrically,  there  are  overloadings  of  To_SQL_Decimal  taking 
SQL_Char_Pkg.SQL_Char,  SQL_Char_Pkg.SQL_Char_Not_Null,  SQLJnt_Pkg.SQL_lnt, 
and  SQLJnt_Pkg.SQLJnt_Not_Null,  etc.  These  functions  are  distinguished  by  their 
parameter  profiles.  For  the  conversion  functions  interconverting  SQL_Decimal  with  other 
null  bearing  types,  if  the  input  is  the  null  value,  the  result  is  the  null  value.  The  functions 
which  convert  SQL_Decimal  object  to  non-null  bearing  types  raise  Null_Value_Error  on  the 
null  input. 

An  abstract  domain  based  on  a  BCD  concrete  representation  is  constructed  from  two  type 
definitions,  two  subtype  definitions,  and  a  package  instantiation  in  the  standard  manner. 

The  types  are  defined  without  a  discriminant  constraint,  which  is  provided  by  the  subtype 
definitions.  The  discriminant  specifies  the  scale  of  the  type.  Just  as  SQL  character  string 
columns  have  fixed  length,  SQL  decimal  columns  have  fixed  scale.  Therefore  objects  are 
declared  to  be  of  the  subtypes. 

Example 

Suppose  the  Weight  of  a  part  is  stored,  in  decimal,  in  tenths  of  some  weight  unit.  The 
Weight  abstract  domain  is  defined  by  the  following  set  of  definitions,  assumed  to  appear  in  a 
domain  definition  package  within  the  scope  of  a  use  for  SQL_Decimal_Pkg. 

Weight  Seal*  :  constant  deciraal_digit«  :=  1; 
type  WeightNN_Ba«e  is  new  SQL_Daciraal_Not_Nu.il  ; 

subtype  Weight_Not_Null  Is  WeightNN_Baaa  (scale  -=>  Weight_Scale) ; 
type  Weight_Baae  is  new  SQL_Decimal; 

Subtype  Weight_Type  is  Weight_Baae  (acale  =>  Weight_Scale) ; 
package  Weight  Opa  is  new  SQL_Decimal_Op# 

(Weight_Base, 

WeightNN_Baae, 

in_#cale  =>  Weight_Scale) ; 
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Notice  the  use  of  a  constant  to  define  the  scale  value  for  the  two  subtypes.  There  is  no  way 
to  define  one  of  those  values  in  terms  of  the  other,  as  there  was  for  character  string  based 
domains.  Notice  also  that  the  unconstrained  types,  not  the  constrained  subtype,  are  passed 
as  the  actual  type  parameter.  The  generic  formal  in_scale  will  be  described  below,  as  part 
of  the  discussion  of  range  constrained  assignment. 

3.5.3.  Range  Constraints  for  Decimal  Types 

Range  constrained  assignment  is  implemented  in  a  novel  way  for  decimal  types.  This  is 
because  the  type  SQL_Decimal_Not_Null  is  not  a  visible  Ada  numeric  type,  as  the  other 
numeric  _Not_Null  types  are.  Thus,  types  derived  from  SQL_Decima!_Not_Null  cannot  be 
directly  constrained.  Range  constraints  for  decimal  types  are  provided  by  parameters 
passed  to  the  instantiation  of  the  generic  _Ops  package.  As  can  be  seen  from  inspection  of 
the  generic  specification  shown  in  Figure  3-4,  there  are  seven  such  parameters.  (The  proce¬ 
dure  parameters  should  default,  as  they  do  for  the  other  generic  _Ops  packages.)  The  use 
of  these  parameters  is  as  follows. 

•  in_scale:  gives  the  scale  of  the  high  and  low  values  of  the  range.  That  scale 
need  not  be  the  same  as  the  scale  of  the  type.  However,  it  is  good  practice  to 
assign  this  parameter  the  scale  of  the  type.  For  types  without  explicit  range 
constraints,  this  is  all  that  need  be  done. 

•  first_sign,  firstjntegral,  firsMractional:  gives  the  sign  “+")  of  the  low 
value  of  the  range,  the  (unsigned)  value  of  the  integral  portion  of  the  low  value 
of  the  range  (the  portion  to  the  left  of  the  decimal  point)  and  the  value  of  the 
fractional  portion  of  the  low  value  of  the  range,  the  portion  to  the  right  of  the 
decimal  point. 

•  last_sign,  lastjntegral,  last_fractional:  as  above,  but  for  the  high  order  value 
of  the  range. 

The  defaults  for  these  parameters  are  arranged  to  be  the  smallest  (most  negative)  and 
largest  values  which  can  be  represented  in  the  underlying  decimal  representation.  Thus  if  no 
values  are  given  for  these  parameters,  the  domain  is  unconstrained. 

The  four  parameters  making  up  the  two  unsigned  values  defining  the  range  are  defined  as 
restricted  strings  (Numeric_String).  This  type  allows  only  character  strings  containing 
decimal  digits.  It  is  defined  in  SQL_Decimal_Pkg  as  is  the  type  Sign_Character,  an 
enumeration  type  having  the  values  and  "+."  The  format  of  the  generic  parameters  was 
chosen  to  avoid  runtime  errors.  Were  these  values  passed  as  two  objects  of  type  string, 
then  malformed  values  could  not  be  detected  at  comp;,e  time. 

The  actual  parameters  are  converted  to  decimal  format  during  the  elaboration  of  the  instan¬ 
tiated  package  by  the  sequence_of_statements  in  the  package  body.  This  means  that  the 
conversion  is  done  at  run  time,  but  only  once  during  program  execution.  The  objects  into 
which  they  are  converted  are  local. 

Example 

Suppose  that  we  wished  to  constrain  the  Weight  domain  defined  earlier  to  allow  only  non¬ 
negative  values.  We  might  then  code  the  package  instantiation  with 
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package  w«i.ght_Op«  is  new  SQL  D«cunal_Op» 

(Weight_Ba»«, 

W«ightNN_Ba*«, 

=>  W«ight_Scal«, 
fir*t_«ign  => 
firat._int.agr ml  =>  "0", 
firat_fractional  =>  "0")  ; 

The  remaining  parameters  may  be  allowed  to  default. 

There  is  no  check  performed  that  the  value  defined  ty  the  combination  first_sign, 
firstjntegral,  first_fractional  is  in  fact  less  than  or  equal  to  the  value  defined  by  iast_sign, 
lastjntegral,  last_fractionai.  If  that  relation  does  not  hold,  any  attempt  to  use  the  generated 
assign  procedures  will  cause  a  runtime  Constraint_Error. 

Instantiation  of  the  generic  _Ops  package  creates  membership  test  functions,  Isjn,  on  the 
types  SQLJDecimal  and  SQL_Decimal_Not_Null.  These  functions  may  be  used  to  prevent 
assign  procedure  calls  from  raising  constraint_error.  Supposing  that  an  object 
A_Decimal_Object  has  some  type  derived  from  SQL_Decimal.  To  ensure  that  it  can  be 
safely  assigned  to  the  object  A_Weight,  of  type  Weight_type,  one  can  code 

if  I*_In  (W«ight_Typ«  (A_D«cim»l_Ob  jact)  )  then 

aacign (A_W«i.ght,  Waight  Typa (A_D«cimal_Ob jact) ) ; 
end  If;  ~ 

The  syntax  of  the  Ada  membership  test  is  <object_ identifier  in  <type_mark>.  As  the  mem¬ 
bership  test  cannot  be  overloaded,  this  syntax  cannot  be  duplicated.  The  allowed  syntax  is, 
however,  a  close  approximation.  The  test  that  an  object  x  may  be  safely  assigned  to  an 
object  of  type  T  is  coded  ls_ln(T(x)),  which  is  self-explanatory. 

The  Isjn  function  which  takes  the  null  bearing  type  SQL_Decimal  returns  Boolean,  not 
Boolean_With_Unknown.  If  the  object  passed  to  the  function  is  in  fact  null,  then  Isjn  returns 
true.  This  is  because  assignment  of  the  null  value  to  a  null  bearing  object  will  not  raise 
constraint  error. 


CMU/SEI-89-TR-16 


43 


generic 

type  With_Null_Type  (acale  :  decimal_digita)  is  limited  private; 
type  Without_Null_Type  (seal*  :  decimal_digita)  is  limited  private; 

In  ical*  :  decimal  digit*  :=  0; 

fir»t_aign  :  Sign_Character  :=  ' ; 

fir*t_int*gral  :  Humeric_String  :  *= 

(1 , . decimal_digit* ' la*t-in_*cale  =>  '9'); 
fir*t_f ractional  :  Numeric_String  ;= 

(1. .in_*c*l*  =>  '  9'  )  ; 

l*«t  *ign  :  Sign_Character  : =  ' ; 

la*t_integral  :  Numeric_String  := 

(1. . decimal_digita ' laat-in_ac*le  =>  '  9' )  ; 
laat_f ractional  :  Numeric_String  :  = 

(1. . in_*c*l*  ->  '  9'  ) ; 

With  function  I*_In_Ba*e  (Right  ;  Without_Null_Type  ; 

Lower,  Upper  :  SQL  Decimal_Not_Null2) 

return  boolean  is  O; 

with  function  I*_In_Bar.e  (Right  :  With_Null_Type; 

Lower,  Upper  :  SQL_Decimal_Not_Null2) 

return  boolean  is  O; 
with  procedure  A*sign_with_cheek 

(Left  :  in  out  Without_Null_Type; 

Right  :  Without_Null_Type; 

Lower,  Upper  :  SQL_Decimal_Not_Null2) 
is  O; 

with  procedure  A*«ign_with_check 

(Left  :  in  OUt  With_Null_Type  ; 

Right  :  With_Null_Type ; 

Lower,  Upper  ;  SQL  Decimal_Not_Null2 ) 
is  O; 

With  function  To_SQL_Decimal_Not_Null2  (Value  :  Without_Null_Type) 
return  SQL_Decimal_Not_Null2  is  o; 

With  function  To_SQLJDecimal_Not_Null2  (Value  :  With_Null_Type) 
return  SQL_Decimal_Not_Null2  Is  O; 

with  function  To_SQL_Decimal_Not_JNull  (Value  :  SQL_Decimal_Not_Null2 ) 
return  Without_Null_Type  is  O  ; 
with  function  To_SQL_Decimal  (Value  :  SQL_Decimal_Not_Null2 ) 
return  with_Null_Type  is  o,- 
package  SQL_Decimal_Op«  Is 

procedure  A*«ign  (Left  :  In  OUt  Without_Null_Type  ; 

Right  :  Without_Null_Type) ; 
procedure  Aaaign  (Left  :  in  out  With_Null_Type; 

Right  :  With_Null_Type) ; 
function  I*_In  (Right  :  Without_Null_Type) 
return  boolean; 

function  l*_In  (Right  :  With_Null_Type) 
return  boolean  ; 

function  With_Null  (Value  :  Without_Null_Type) 
return  With_Null_Type  ; 

function  Without_Hull  (Value  :  With_Null_Type) 
return  Without_Null_Type  ; 
end  SQL_Decimal_Op* ; 

Figure  3-4:  The  Generic  Subpackage  SQL_Decimal_Ops 
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3.6.  Data  Types  Not  in  the  SQL  Standard 

The  previous  sections  deal  with  the  data  types  supported  by  ANSI  standard  SQL  [2].  Many 
database  management  systems  extend  the  standard  to  other  types  and  some  support  the 
standard  types,  particularly  the  string  type,  in  non-standard  ways.  This  section  outlines  the 
way  in  which  a  user  of  the  SAME  can  extend  the  data  typing  facilities.  This  is  done  by  pro¬ 
viding  a  package  which  supports  the  new  type. 

To  design  a  new  support  package,  one  must  first  decide  on  the  database  representation  of 
the  type  and  on  the  method  by  which  null  values  of  the  type  will  be  represented.  It  is  likely 
that  the  database  representation  can  be  simulated  by  one  of  the  types  in  sql_standard.  If 
this  is  not  possible  or  desirable,  a  new  package,  with  the  name  DBMS_Standard,23  should 
be  constructed  to  contain  the  concrete,  database  representation  as  an  Ada  type. 

It  is  strongly  recommended  that  the  null  value  representation  be  safe,  in  the  sense  that  null 
values  cannot  inadvertently  and  incorrectly  be  used  as  though  tney  were  not  null.  This  sug¬ 
gests  an  abstract,  private  type  to  represent  domain  values  at  the  abstract  interface.  If  that 
route  is  chosen,  the  support  package  should  include  null  testing  functions  ls_Null  and 
Not_Null  and  conversion  functions  With_Null  and  WithoutJMull.  A  null  value  for  the  type 
should  also  be  available  in  the  package  specification.  In  the  SAME  standard  packages  dis¬ 
cussed  so  far,  the  null  values  Null_SQL_lnt,  Null_SQL_Char,  etc.,  are  defined  as 
parameterless  functions,  rather  than  as  private  constants.  This  treatment  causes  a  null 
value  to  be  created  for  each  type  derived  from  the  types  in  the  SAME  standard  packages.  In 
every  case,  a  function  for  converting  a  non-null  value  from  the  concrete  representation  to 
the  abstract  one  snould  be  proviaed  to  the  buiiders  or  abstract  modules. 

If  the  model  of  the  previous  sections  is  followed,  i.  e.,  if  each  abstract  domain  has  two  type 
representatives,  a_Not_Null  visible  Ada  type  and  a  private  _Type  supporting  nulls,  gener¬ 
ating  the  conversion  functions  With_Nuil  and  Without_Null  by  generic  instantiation  will  tie  the 
two  types  together.  Other  functions  supplied  by  the  package  will  depend  on  the  nature  of 
the  type  being  defined  and  the  designer’s  choice. 

3.6.1.  Ada  Enumeration  Types 

This  section  illustrates  user  extensions  to  the  SAME  typing  model  with  an  implementation  of 
Ada  enumeration  types.  Enumeration  types  can  be  represented  in  the  database  as  either  an 
integer  or  as  a  character  string.  The  integer  encoding  will  save  space  but  will  be  incom¬ 
prehensible  to  any  non-Ada  database  applications.  The  character  string  representation  will 
cost  space,  but  will  make  the  type  meaningful  to  other  applications,  such  as  any  interactive 
SQL  tool  or  report  writer  supplied  by  the  database  vendor.  The  representation  decision  must 
be  made  at  database  design  time,  so  that  the  proper  column  definitions  can  be  made.  This 
decision  can  be  made  separately  for  each  enumeration  type  to  be  stored  in  the  database. 

The  treatment  chosen  for  the  null  value  parallels  the  treatment  in  the  standard  packages.  A 
limited  private  record  type  definition  encapsulates  the  enumeration  type  with  a  Boolean.  As 
the  type  is  private,  the  enumeration  value  can  be  accessed  only  through  the  functions  pro¬ 
vided. 


^e.g.,  lngres_Standard,  Oracle_Standard,  DB2_Standard,  etc. 
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The  treatment  uses  the  enumeration  type  itself  as  the  _Not_Null  type.  It  defines  both  the 
three-valued  (Boolean_with_Unknown)  and  the  two-valued  (Boolean)  comparison  operators 
(Equals,  Not_Equals,  (or  =,  /=  (implicitly))  <,  <=,  etc),  and  the  functions  Succ,  Pred,  Pos, 

Val,  Image  and  Value  for  the  limited  private  _Type.  These  last  two  functions  (Image  and 
Value)  are  also  defined  for  the  _Not_Null  type.  These  functions  take  (Value)  and  return 
(Image)  objects  of  the  SAME  predefined  types  SQL_Char  (or  SQL_Char_Not_Null  when  ap¬ 
plied  to  the  _Not_Nul!  type).  This  usage  is  to  accommodate  character  set  independent  pro¬ 
grams. 

The  specification  for  the  package  SQL_Enumeration_Pkg  appears  in  Figure  3-5.  It  is  a 
generic  package  with  the  enumeration  type  as  the  formal  parameter.  Even  if  the  limited 
private  type  were  declared  with  no  operations  other  than  the  test  and  conversion  functions,  it 
would  still  be  necessary  to  make  this  package  a  generic.  The  body  of  the  package  appears 
in  Appendix  C. 

Example 

Suppose  the  Status  of  a  supplier  has  only  a  small  number  of  legal  values.  This  can  occur 
even  if  the  database  design  was  not  developed  with  Ada  in  mind.  It  may  be  known  to  appli¬ 
cation  developers  that  a  Status  of  zero  indicates  an  unacceptable  supplier,  five  an  accept¬ 
able  supplier  and  ten  a  preferred  supplier.  This  information  will  be  hidden  in  the  application 
code.  Ada  allows  this  knowledge  to  be  made  visible  in  the  type  definition  while  freeing  the 
application  programmer  from  the  need  to  know  it.  The  Status  abstract  domain  may  be  en¬ 
coded  as  follows. 

type  Statu«_Not_Null  is  (Unacceptable,  Acceptable ,  Preferred) ; 
for  Statuc_Not_Hull  use 

(Unacceptable  =>  0, 

Acceptable  =>  5, 

Preferred  =>10); 

package  Statua_Pkg  is  new  SOL_Enumerati.on_Pkg  (Statu«_Not_Null)  ; 
type  Status_Type  is  new  Statua_Pkg . SQL_Enumeration; 

Notice  that  the  _Type  is  derived  from  the  private  type  generated  from  the  package  instan¬ 
tiation.  This  gives  the  two  types  making  up  the  abstract  domain  similar,  conventional  names. 
It  also  means  that  the  package  instantiation  need  not  be  made  visible  to  the  application 
program  (see  Chapter  5). 

The  task  of  converting  from  the  database  representation,  in  this  case  SQL_Standard.lnt  (or 
possibly  SQL_Standard.Smallint),  to  the  abstract  representation,  the  types  Status_Not_Null 
or  Status_Type,  is  the  responsibility  of  the  abstract  module.  Section  4.2  describes  these 
modules.  In  this  case,  the  integer  representation  to  be  used  on  the  database  is  that  given  by 
the  for ...  use  representation  clause.  It  is  necessary  to  use  Unchecked_Conversion  to  ac¬ 
complish  this.24  Unchecked_Conversion  is  a  predefined  generic  function.  Its  use  is  il¬ 
lustrated  in  the  following  template. 


24Unchecked_Conversion  is  a  Chapter  13  feature.  Care  must  be  taken  in  its  use. 
- - - - -  — — - - - - - — - 
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with  Dnch«ck«d  Conversion; 


function  Cnvrt_statu«_ln  is  new 

Onoh«ckad_Convarg ion  (Integer,  Status  not  Null) ; 
function  Cnvrt_Status_Out  is  new 

Onchecked_Conver«ion  (Statu»_not_Null,  Integer) ; 


begin 

<Application  Variable>  :  = 

With_Null (Cnvrt_Status_In (^Database  Variable>) ) ; 

<Database  Variable>  : = 

Cnvrt_Statue_Out (Without_Null (<Application  Variable>) )  ; 


end; 


These  assignment  statements  assume  that  the  database  value  involved  is  not  null.  See 
Section  4.2  for  more  details. 

It  is  possible  to  use  the  position  (POS)  of  an  enumeration  literal  within  the  enumeration  type 
instead  of  its  representation  as  the  database  encoding,  if  the  database  is  being  defined  with 
the  Ada  applications.  Use  of  the  representation  encoding  may  help  prevent  inadvertent 
changes  in  the  enumeration  type  definition  from  destroying  the  meaning  of  the  database. 

If  the  character  string  representation  is  chosen,  the  mapping  between  database  and  internal 
representations  is  accomplished  with  the  Image  and  Value  functions  created  by  the  instan¬ 
tiation  of  SQL_Enumeration_Pkg.  Care  must  be  taken  to  ensure  the  database  columns  stor¬ 
ing  these  strings  are  long  enough  to  accommodate  growth.  Care  must  also  be  taken  to  strip 
or  pad  blanks  as  needed  and  to  ensure  the  case  of  the  database  string  is  such  that  non-Ada 
programs,  which  may  be  case  sensitive,  can  recognize  them.  Although  character  string  rep¬ 
resentation  takes  more  space,  it  has  the  advantage  of  being  readable  by  non  Ada  programs 
and  is  relatively  impervious  to  changes  in  the  enumeration  type,  provided  enough  space  has 
been  reserved  initially. 

3.6.2.  Date  Time  Types 

Many  database  management  systems  extend  the  ANSI  standard  by  offering  a  date  -  time 
data  type.  The  follow-on  standard,  SQL2,  under  development  by  ANSI  [4],  also  provides  a 
date  -  time  data  type.  This  section  develops  support  for  date  -  time  types  as  yet  another 
example  of  user  extensions  to  the  SAME.  As  no  standard  treatment  of  date  -  time  has  been 
established,  two  distinct  support  packages  are  presented  here.  One  of  the  packages  sup¬ 
ports  the  SQL2  date  -  time  data  type;  the  other  supports  Ingres  date  -  time. 

The  two  support  packages  have  a  lot  in  common.  In  both  cases,  values  appear  at  the  con¬ 
crete  interface  as  character  strings.  Therefore,  in  both  cases,  the  concrete  type  used  to 
store  dates  is  a  derived  type  of  SQL_Char_Not_Null.  In  both  cases,  limited  private  types  are 
declared  which  support 

•  Null  values  for  date  -  times.  The  test  and  conversion  functions  and  three- 
vaiued  logic  and  arithmetic  are  supported  (see  Section  3.1). 

•  Date  time  arithmetic.  The  DBMS  date  time  arithmetic  is  defined  by  appropriate 
functions  and  operators. 
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With  S QL_B oo  1  e an_P leg ;  use  SOL_Boolsan_P)cg; 
generic 

type  SQL_Enumsration_Not_Null  is  <<>)  ; 
package  SQL_Enumsration_P)cg 
is 

-  Possibly  Null  Enumeration  - 

type  SQL_Enumsration  is  private; 

function  Null_SQL_Enurosration  return  SQL_£numsration; 
conversion  function* 

function  Without_Null  (Value  :  in  SQL_Enumsration) 
return  SQL  Enumeration_Not_Null  ; 

—  raise*  Null  Value  Error  on  the  null  input 
function  With_Null (Value  :  in  SQL_Enumsration_Not_Null) 

return  SQL__Enumaration; 

procedure  Assign  (Left  ;  in  out  SQL_Enumeration; 

Right  :  in  SQL_Enurasration)  ; 

—  Three-valued  comparison  operators;  raise  no  exceptions 
function  Equals  (Left,  Right  ;  SQL_Enumeration) 
return  Boolaan_with_Onknown; 
function  Not_Equals  (Left,  Right  :  SQL_Enumaration) 
return  Boolean  with_Dnknown ; 
function  "<"  (Left,  Right  :  SQL_Enumeration) 
return  Boolean  with_Onknown ; 
function  ">”  (Left,  Right  :  SQL_Enumsration) 
return  Boolaan_with_Cnknown; 
function  "<="  (Left,  Right  :  SQL_Enumeration) 
return  Boolaan_with_Onlenown; 
function  ">="  (Left,  Right  :  SQL_Enumaration) 
return  Booi®an_with_0nlcno»m; 

function  Is_Null  (Value  :  SQL_Enumeration)  return  Boolean; 
function  Not_Null  (Value  ;  SQL  Enumeration)  return  Boolean; 

--  ' Pred,  ' Succ  return  the  null  value  on  the  null  input 

—  'Image,  ' Pos  raise  Null  Valua_Error  on  the  null  input 
function  Pred  (Value  :  in  SQL_Enumaration) 

return  SQL_Enumeration; 
function  Succ  (Value  :  in  SQL_Enumeration) 
return  SQL_Enumeration; 
function  Pos  (Value  :  in  SQL_Enumeration) 
return  Integer; 

function  Image  (Value  in  SQL  Enumeration) 
return  String; 

function  Val  (Value  :  in  Integer) 
return  SQL_Enumeration; 
function  Value  (Value  :  in  String) 
return  SQL_Enumeration; 

private 

type  SQL_Enumeration  is  record 
Is_Null:  Boolean  : =  true; 

Value:  SQL_Enumeration  Not_Null; 

end  record; 

end  SQL  Enumeration  Pkg; 

Figure  3-5:  The  Package  Specification  SQL_Enumeration_Pkg 

The  definitions  of  the  limited  private  types  are  optimized  for  doing  arithmetic.  The  visible, 
_Not_Null  types,  derived  from  SQL_Char_Not_Null,  are  optimized  for  displays.  Both 
packages  contain  _Ops  generic  subpackages  for  generating  conversion  functions  between 
the  _Not_Nu!l  and  _Type  types.  Both  packages  also  contain  functions  for  converting  be- 


48 


CMU/SEI-89-TR-16 


tween  the  _Type  and  the  most  nearly  appropriate  predefined  Ada  types,  Calendar.time  and 
Standard. duration.  These  conversions  are  necessarily  inexact. 

Support  for  the  SQL2  date  -  time  type  is  provided  by  the  package  SQL_Date_Pkg,  the  spec¬ 
ification  of  which  can  be  found  in  Appendix  C.  SQL2  defines  two  date  -  time  types,  Date  and 
Interval.  A  date  is  a  specific  moment  in  time;  an  interval  is  a  period  of  time.  Both  of  these 
types  can  be  modified  by  a  so-called  “date-time  qualifier."  This  qualifier  specifies  the  preci¬ 
sion  of  a  date  or  interval.  Date-time  qualifiers  specify  the  most  and  least  significant  portions 
of  a  date  or  interval  to  be  recorded.  A  database  table  column  having  date  or  interval  type 
has  an  associated  date  time  qualifier.  Thus,  all  values  in  the  column  have  the  same  format. 
See  [4]  for  more  details. 

The  declaration  of  an  abstract  domain  for  date  or  interval  types  must  also  include  date-time 
qualifier  information.  The  discriminants  of  the  types  SQL_Date  and  SQLJnterval  capture 
that  information.  The  discriminants  are  specified  in  the  associated  type  declarations  within 
the  abstract  domain  declaration,  as  exemplified  by  the  following  domain  package. 

With  SQL_D«t«_Pkg;  Use  SQL_Dat«_Pkg; 
package  D«t«_Domai_n  is 

type  D*t«NN_Ba»«  Is  new  SQL_Dat«_Not_Null; 

subtype  Dafc«_Not_Null  Is  D*t«NN_Ba»«  (1..10); 

type  D»t«_Typ«  is  new  SQL_Dat*  (Proo=>yoax,  To=>Day, 

Fractional=>0) ; 

package  Dafc«_Op«  is  new  SQL_Date_Opa  (Data__Typ« ,  DateHN_Bas«)  ; 

type  Month* NN_Baa«  is  new  SQL_Data_Not __Null  ; 

Subtype  Monfch*_Nofc  Null  Is  Month*NN_Ba*« ( 1 . . 2)  ; 

type  Month*_Typ«  is  new  SQL_Intarval (From=>Month,  laading=>2, 

To=>Month,  Fractxonal=>0 ) ; 

package  Month*_Op«  is  new  SQLJDat*_Op a 

(Montha_Typa ,  Month*NN_Baa«) ; 


package  Data_Month*_op*  is  new 

SQL_Dafc*_Intarval_Op*  (Dat»_Typa,  Month*_Typ® ) ; 


end  Dat«_Domain ; 

Here  objects  o'  Date  JTyoe  record  a  year,  a  month,  and  a  day.  The  _Not_Null  string  version 
of  Date  is  ten  characters  long,  as  SQL2  defines  the  character  representation  of  such  dates 
to  have  the  form  yyyy-mm-dd.  Objects  of  Months_Type  are  intervals  recorded  in  months. 
Intervals  from  0  to  99  months  can  be  recorded  as  objects  of  MonthsJType. 

As  before,  the  generic  subpackage  SQL_Date_Ops  generates  conversion  functions  be¬ 
tween  the  _Not_Null  and  _Type  types  of  a  domain.  The  generic  subpackage 
SQL_Date_lnterval_Ops  generates  arithmetic  functions  on  the  date  and  interval  types  which 
are  the  actual  type  parameters.  In  order  for  the  application  program  to  do  date  arithmetic 
such  as  adding  or  subtracting  an  interval  to  or  from  a  date  and  subtracting  two  dates  to  form 
an  interval,  an  instantiation  of  SQL_Date_lnterval_Ops  for  the  types  must  exist  in  the 
domain  package.  This  "cross  product"  will  not  require  very  many  package  instantiations,  as 
there  are  likely  to  be  very  few  distinct  date  or  interval  domains.  Most  dates  and  intervals  are 
inherently  comparable. 
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The  following  example  shows  how  the  Date_Domain  can  be  used. 

with  Dat*_Domain;  use  Dat»_Doiuaiii; 
with  t*xt_io;  use  t*xt_io; 
procedure  u*«_data*  is 

use  Dat*_Op*,  Month*  Op*,  Dat*_tav nth*_Op* ; 

Today_Not_Hull  :  Data_Hot_Null  :=  to_*ql_char_not_null ("1988-10-25") ; ; 

Today  :  Dat*_Typa ; 

Two_Monfchs_Not_Null  :  Month*_Not_Hull  :=  to_*ql_char_not_null ( "  2"); 

Two_Monfch*  :  Month*_Typ* ; 

begin 

Para*  And  Assign (Two _ Month* ,  Two_Month*_Not  Hull ) ; 

Par*a_And_A*sign (Today,  Today_Not_Null) ; 

put  lln* (to  string (without_Null (Today  +  Two  Month*) ) ) ; 
end  u**_dat«a; 

Notice  that,  as  a  derived  types  of  SQL_Char_Not_Null,  Date_Not_Null  and 
Months_Not_Null  inherit  conversion  functions  from  and  to  the  predefined  type  string.  The 
procedure  Parse_And_Assign  replaces  the  functions  With_Null  in  other  support  packages. 
This  procedure  uses  the  discriminants  of  the  left,  output  operand  to  determine  the  meaning 
of  the  right,  character  string  input  operand.  Parse_And_Assign  can  raise  Constraint_Error  if 
the  output  discriminants  are  not  legal  according  to  the  rules  of  SQL2. 

The  Ingres  date  time  data  type  is  supported  by  a  package  lngres_Date_Pkg,  the  specifi¬ 
cation  of  which  can  be  found  in  Appendix  C.  Ingres  dates  are  markedly  different  from  SQL2 
dates.  There  is  only  one  type,  rather  than  two,  and  row  columns  of  date  type  may  contain 
either  dates  or  intervals.  Further,  the  dates  and  intervals  have  varying  formats.  Thus,  to  de¬ 
termine  the  meaning  of  a  given  value  of  a  date  column,  it  is  necessary  to.  examine  the  value. 
See  [1 3]  for  details. 

lngres_Date_Pkg  defines  a  single  limited  private  type,  lngres_Date,  for  holding  values  of 
Ingres  date  columns.  As  earlier,  this  type  is  optimized  for  date  arithmetic;  whereas 
lngres_Date_Not_Null  is  optimized  for  display.  The  discriminant  of  the  type  lngres_Date  is 
used  to  record  the  nature  of  a  value  in  an  object  of  the  type.  The  type  of  the  discriminant, 
lngres_Date_Format,  is  an  enumeration  type  having  the  value  set  (Datetime,  Interval, 
Unknown).  The  lngres_Date  type  definition  specifies  a  default  of  Unknown  for  the  dis¬ 
criminant.  Variables  of  lngres_Date  type  can  be  declared  without  discriminant  constraints. 
Such  variables  can  contain  either  dates  or  intervals,  just  as  Ingres  database  columns  of  type 
date  can  contain  either  class  of  values.  The  declaration  of  an  abstract  domain  based  on  an 
Ingres  date  type  is  illustrated  by  the  following. 

with  Ingr*«_D»t*_P kg ;  use  lngr**_D»t*  Pkg; 
package  Ingra»_Dat*_Domain  is 

type  D*t*_Not_Null  is  new  Ingr**_Dat*_Not_Null; 
type  D*t*_Typ*  is  new  Ingr**_Data; 

package  D*t*_Op*  Is  new  Ingra*_Dat*_Op*  (D*t*_Typ*,  D»t*_Not_Null) ; 
end  Ingres  Data  Domain; 

Notice  that  the  _Not_Nu!l  type  is  already  constrained  by  the  definition  of 
lngres_Date_Not_Nu!l.  All  Ingres  dates  and  intervals  are  exactly  25  characters  in  length. 
There  is  no  need  for  a  cross  product  package  as  there  was  for  SQL2.  The  following  program 
uses  Ingres  dates. 
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With  Ingr««_Dafce_Domain;  use  Ingr«s_Dat«  Domain; 
With  Text_IO;  use  Taxt_IO; 
procedure  0«»_Ingrae_Data»  is 


use  Date_Opa; 


Data_Stringl 

Data_String2 

Dafcal_Not_Null 
Data2_Not_Null 
Datal,  Dat«2  : 


string (Data_Not_Null '  Ranga)  :=  "1988-oct-25"  & 

( 12 .  . Data_Not_Null ' Last  =>  '  '); 

string  (Dats_Not_Null ' Rangs)  :=  "2  ran"  £ 

(5 . . Data_Not_Null' Last  =>  '  '); 

:  Dats  Not_Null  : =  to_aql  char_not_null (Data_Stringl ) ; 
:  Dats_Not_Null  :=  to_sql_char_not_null (Data_String2) ; 
Dats_Typa ; 


begin 

assign (Datsl ,  With_Null (Datsl_Not_Null) ) ; 
assign (Dats2 (  With_Null (Dats2_Not_Null) ) ; 
put_lins (to_string (without_null (Data2  +  Datsl) ) ) ; 

end  Dss  Ingres  Dates; 

Both  treatments  of  the  date  -  time  type  presented  in  this  section  have  as  their  design  goal 
the  creation  of  an  abstract  type  which  simulates  a  database  type.  Thus  the  types  and  opera¬ 
tions  in  SQL_Date_Pkg  simulate  SQL2’s  treatment  of  dates;  the  types  and  operations  in 
lngres_Date_Pkg  simulate  Ingres'  treatment  of  dates.  Applications  using  these  packages 
can  operate  on  dates  in  the  same  way  that  the  DBMS  does. 

In  constructing  new  data  type  support  packages,  the  user  of  the  SAME  is  free  to  substitute 
other  design  goals  for  that  of  DBMS  simulation.  For  example,  it  may  be  desirable  to  con¬ 
struct  a  type  support  package  for  use  with  Ingres  that  makes  its  date  type  more  closely 
resemble  the  emerging  SQL2  standard.  Such  a  support  package  may  improve  the  portability 
of  applications  which  use  it.  (Of  course,  it  will  not  make  the  Ingres  SQL  portion  of  the  appli¬ 
cation  treat  dates  in  the  style  of  SQL2.)  The  user  is  permitted  to  extend  the  SAME  with 
non-standard  data  types  in  any  way  that  he  or  she  sees  fit.  It  is  strongly  suggested  that  such 
extensions  maintain  the  safe  treatment  of  nulls  which  is  a  defining  characteristic  of  the 
SAME  standard  packages. 


3.7.  Packaging  the  Type  Definitions 

Prior  sections  deal  with  data  definition  at  the  level  of  the  individual  abstract  domains.  This 
section  begins  the  process  of  describing  the  database  at  higher  level  of  granularity.  The 
level  of  the  tuple  or  row  is  not  described  until  Chapter  4;  the  level  of  the  relation  or  table  is 
never  reached,  as  Ada  programs  do  not  deal  with  tables  as  a  whole,  but  only  with  rows 
within  tables,  one  at  a  time. 

The  identification  of  the  abstract  domains  over  which  a  database  is  defined  occurs  during 
the  database  design  process.  Most  database  design  methodologies  lose  this  information 
however,  as  database  technology  has  evolved  without  regard  to  the  needs  of  strongly  typed 
languages  such  as  Ada.  In  developing  the  Ada  description  of  the  database  for  use  with  the 
SAME,  it  may  be  necessary  to  retro-fit  this  information.  This  section  assumes  that  the  Ada 
description  is  developed  from  the  SQL  description. 
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The  first  problem  to  be  addressed  is  the  re-identification  of  the  abstract  domains.  In  the  ex¬ 
ample  developed  in  the  introduction  (see  Figure  1-6),  the  abstract  domains  are  identified  by 
the  attribute  or  column  names.  Thus  the  columns  named  PNO  in  the  tables  P  and  SP  have 
the  same  abstract  domain;  so  do  the  columns  named  CITY  in  the  tables  S  and  P.  Reliance 
on  column  names  is  not  recommended.  There  is  no  rule  in  database  design  methods  nor  in 
SQL  that  enforces  or  even  suggests  such  column-naming  practices.  In  general,  the  problem 
is  determining  whether  any  given  pair  of  columns  share  an  abstract  domain. 

The  number  of  columns  in  a  real  world  database  description  is  generally  quite  large  and  the 
task  of  examining  each  pair  is  overwhelming.  Most  such  pairs  are  obviously  not  over  the 
same  domain,  making  the  task  simpler  than  this  crude  analysis  suggests.  There  is  one  case 
in  which  columns  trom  two  distinct  table  definitions  are  obviously  over  the  same  domain: 
the  foreign  key.  A  foreign  key  is  a  column  of  one  table,  the  values  of  which  are  keys  of 
another  table.  These  columns  clearly  have  the  same  domain.  In  the  example,  SNO  and 
PNO  are  foreign  keys  in  the  SP  table.  It  is  for  this  reason  that  the  PNO  columns  of  P  and  SP 
have  the  same  domain. 

Once  the  foreign  keys  are  recognized,  remaining  column  pairs  must  be  decided  on  a  case- 
by-case  basis.  Trit;  rule  to  follow  is  the  comparison  rule:  "Does  it  make  sense  to  compare 
values  of  these  columns?”  If  the  answer  is  yes,  the  columns  probably  have  the  same 
domain.  For  this  reason,  the  columns  CITY  in  S  and  P  of  the  example  can  be  seen  to  have 
the  same  domain.  This  rule  frequently  applies  to  fields  containing  dates.  The  Date_Created 
and  Date_Modified  columns  of  a  record  describing  a  product  are  probably  over  the  same 
domain.  On  the  other  hand,  the  Birth_Date  column  of  an  employee  record  may  well  have  a 
different  domain.  It  is  the  designer's  responsibility  to  make  these  determinations. 

Once  the  abstract  domains  have  been  identified  and  the  Ada  type  definitions  have  been 
written,  the  definitions  are  assembled  into  packages,  called  domain  packages,  and  compiled 
into  Ada  libraries  for  the  use  of  programmers.  The  essential  rule  of  these  packages  is  that 
they  must  be  disjoint;  that  is,  no  abstract  domain  should  be  declared  in  more  than  one 
domain  package.25  The  reason  for  this  rule  is  obvious.  If  the  type  and  package  declarations 
making  up  an  abstract  domain  declaration  are  duplicated  in  more  than  one  package,  the 
result  is  the  declaration  of  two  distinct  domains. 

There  are  no  hard  and  fast  rules  for  determining  which  abstract  domain  declarations  to  col¬ 
lect  into  domain  packages.  The  rule  which  places  each  domain  declaration  into  its  own 
package  satisfies  the  disjointness  rule,  but  may  result  in  excessively  many  packages. 

A  useful  technique  is  to  begin  by  collecting  abstract  domains  into  possibly  overlapping  sets 
and  then  reducing  the  sets  by  intersection  until  a  disjoint  collection  is  obtained.  The  initial 
collection  can  be  created  by  letting  each  base  table  definition  create  a  set  in  the  collection. 
An  alternative  has  each  set  in  the  original  collection  correspond  to  an  application  view,  that 
is,  be  the  collection  of  abstract  domains  of  interest  to  a  given  application.  This  alternative 
requires  that  the  designer  have  knowledge  of  the  applications  to  be  run  against  the  data¬ 
base.  Such  information  is  often  available  during  the  database  design.  The  advantage  of 
using  application  views  is  that  they  map  naturally  to  the  application  programs. 


25The  declaration  of  an  abstract  domain  is  the  declaration  of  the  two  types,  and  for  character  string  data  two 
subtypes,  plus  the  package  instantiation,  as  described  in  the  preceding  subsections. 
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Example 

In  the  Parts  Suppliers  example,  assume  the  existence  of  three  application  views. 

1.  A  Parts  view,  concerned  only  with  information  about  Parts. 

2.  A  Suppliers  view,  concerned  only  with  information  about  Suppliers. 

3.  An  Orders  view,  concerned  with  all  the  information  in  the  Database. 

From  these  views,  the  initial  collection  of  sets  of  domains  is  as  follows. 

1.  For  Parts,  the  set  containing  the  domains  PNO,  PNAME,  COLOR,  WEIGHT 
and  CITY. 

2.  For  Suppliers,  the  set  containing  the  domains  SNO,  SNAME,  STATUS,  and 
CITY. 

3.  For  Orders,  the  set  containing  the  domains  PNO,  SNO,  PNAME,  SNAME, 

STATUS,  COLOR,  WEIGHT,  CITY  and  QTY. 

To  complete  the  design  of  the  domain  packages,  take  intersections  of  these  sets.  The  final 
design  appears  in  Figures  3-6  and  3-7.  The  Parts  application  will  bring  into  context  (with) 
the  packages  CITY_Definition_Pkg  and  Parts_Defmition_Pkg.  The  Supplier  application  will 
need  CITY_Definition_Pkg  and  Suppl:ers_Definition_Pkg.  The  Orders  application  will  need 
all  four  packages. 

The  pattern  of  Figures  3-6  and  3  7  is  common.  A  few  domains  will  be  shared  by  multiple 
views.  These  domains  will  appear  in  small  packages.  The  remaining  domains  will  be  unique 
to  an  application.  In  most  real  world  relational  databases,  the  majority  of  the  domains  are 
unique  to  an  application.  ■ 

An  application  may  need  domains  defined  specifically  for  it.  If  an  application  deals  only  with 
preferred  suppliers,  that  is,  suppliers  with  Status  >  100,  the  abstract  sub-domain 
Preferred_Status,  illustrated  in  Section  3.3,  is  such  an  application-specific  domain.  Gll.ci 
application-specific  domains  may  arise  from  SQL  expressions  (see  Section  4.1 .1 ).  For  the 
sake  of  exposition,  suppose  the  Parts  table  were  to  contain  Length,  Width  and  Height 
columns  and  that  these  columns  had  the  abstract  domain  Meters.  If  part  volume, 
(Length*Width*Height),  is  returned  from  an  SQL  statement,  its  abstract  domain  is 
Cubic_Meters.  There  may  be  no  database  column  with  this  domain.  The  definitions  of  such 
application-specific  domains  can  either  be  included  in  the  package  of  application-unique 
database  domain  definitions  or  put  into  a  package  by  themselves. 

Except  for  the  rule  that  states  that  domain  packages  must  be  disjoint,  the  other  rules  for  the 
iurmation  of  domain  packages  are  heuristics.  The  smaller  the  domain  packages,  the  more 
packages  need  to  be  defined  and  controlled  in  configuration  management.  Larger  domain 
packages  may  cause  unnecessary  recompilations.  In  the  Parts-Suppliers  example,  a  given 
program  or  component  of  the  Parts  application  may  need  visibility  to  WEIGHT  but  not  to 
COLOR,  for  example.  If,  during  database  evolution,  the  definition  of  the  COLOR  domain  is 
changed,  that  program  or  component  may  be  unnecessarily  marked  for  recompilation. 
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City  Abstract  Domain 

With  SQL_Char_Pkg;  use  SQL_Chax_Pkg; 
package  CITY_Definition_Pkg  is 

type  CITYNN_Bas«  is  new  SQL_Char_Not_Null; 
subtype  CITY_Not_Null  is  CITYNN_Ba««  (1..15); 
type  CITY_Ba««  is  new  SQL_Chax; 

subtype  CITY_Typ«  is  CITY_Baa«  (CITY_Not_Null ' Length)  ; 
package  ciTY_Opa  is  new 

SQL_Char_Ope(CITY_Baaa,  CITYNN_Baa«) ; 
end  CITY_Da£initi.on_Pkg; 

QTY  Abstract  Domain 

With  SQL_Int_Pkg;  Use  SQL_Xnt_Pkg; 
package  QTY_p«finitaon_Pkg  Is 

type  QTY_Not_Null  is  new  SQL_Int__Not_Null 

range  0  ..  SQL_Int_Not_Null ' LAST; 
type  QTY_Type  is  new  SQL_Int ; 
package  QTY_Opa  is  new 

SQL_Int_Opa (QTY_Typa,  QTY_Not_Null) ; 
end  QTY_Daf inition_Pkg; 

Domains  Unique  to  Parts 

With  SQL_Char_Pkg;  use  SQL_Char_P kg ; 

With  SQL_Int_Pkg;  use  SQL_Int_Pkg; 
package  Part«_D«£.inition_Pkg  is 

type  PNONN_Ba««  is  new  SQL_Char__Not_Null ; 
subtype  PNO_Not_Null  is  PNONNJBaaa  (1..5); 
type  PNO _ Base  is  new  SQL_Char; 

subtype  PNC_Typ«  is  PNO_Ba««  (PNO_Not_Null ' Length) ; 
package  PNO_Op«  is  new 

SQL_Char_Opa(PNO_B*«e,  PNOKN_Ba»e) ; 

type  PNAMENN_Ba«e  is  new  SQL_Ch*r_Not_Null ; 
subtype  PHAME_Not_Null  IS  PNAMENN_Baaa  (1..20); 
type  PNAMEJBaae  is  new  SQL_Char; 

subtype  PNAME_Typ«  is  PNAME_Ba»«  (PKAME_Not_Null' Length) ; 
package  PNAME_Ope  is  new 

SQL_Chax_Ope  (PUAME_Baa« ,  PNAMENN_Ba«e)  ; 

type  COLORHN_Ba*e  is  new  SQL_Chax_Not_Null; 
subtype  COLOR_Not_Null  is  COLORNN_Ba«e  (1 . . 6) ; 
type  COLOR_Baae  is  new  SQL_Char; 

subtype  COLOR_Type  is  COLOR_Baa«  (COLOR_Not_Null' Length) ; 
package  cOLOR_Op#  is  new 

SQL_Char_Ops (COLOR_Baee,  COLORNNJBase) ; 

type  Weight_Not_Null  is  new  SQL  Int_Not_Null 
range  0  . .  SQL_int_Not_Null; 
type  Weight_Typ«  is  new  SQL_Int; 
package  Weight_Opa  is  new 

SQL_Int_Opa (Weight_Type ,  Weight_Not_Null) ; 
end  Part«_Def inition_Pkg; 

Figure  3-6:  The  Domain  Packages  for  Suppliers-Parts 
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Domains  Unique  to  Suppliers 

with  SQL_Char_Pkg;  Use  SQL_Char_Pkg ; 

With  SQL_Int_Pkg;  use  SQL_Int_Pkg; 

package  Suppli«r*_D«f  lniti.on_P)cg  is 

type  SNONN_Ba*e  is  new  SQL_Char_Not_Null; 
subtype  SNO_Not_Null  is  SNONN_b1*«  (1..5); 
type  SNO_Ba««  is  new  SQL_Char; 

SUbtype  SNO_Typ*  is  SNO_Bas*  (SNO_Not_Null '  Leng-th)  ; 
package  SNO_op«  is  new 

SQL_Ciiar_Op«  ( SNO_Ba*« ,  SNONN__Bas« )  ; 

type  SNAMENN_Ba««  is  new  SQL_Char_Not_Null  ; 
subtype  SNAME_Not_Null  is  SNAMENN_Ba*«  (1..20); 
type  SNAME_Ba*«  is  new  SQL_Char; 

SUbtype  SNAME_Type  is  SNAME_Baa«  (SNAME_Not_Null ' Length) ; 
package  sNAME_Op*  is  new 

SQL_Char_Ops (SNAME_Baa«,  SNAMENN_Bae«) ; 

type  Sfcatu*_Not_Null  IS  new  SQL_Int_Not_Null 
range  o  . .  loo,- 

type  Statu*_Typ*  is  new  SQL_Int; 
package  statu*_Op*  is  new 

SQL  Int_Op» (Sfcatua_Typ« ,  Statua_Not_Null) ; 
end  Supplier*  Def inition_Plcg; 


Figure  3-7:  The  Domain  Packages  for  Suppliers-Parts,  cont’d. 


3.8.  The  Package  SQL_Base_Types_Pkg 

The  method  of  abstract  domains  for  database  description  presented  in  this  section  will  gen¬ 
erally  produce  a  large  number  of  distinct  abstract  types.  This  is  in  keeping  with  good  Ada 
design  practice,  in  which  the  type  of  an  object  gives  some  indication  as  to  the  semantics  of 
its  values.  Due  to  Ada’s  implementation  of  strong  typing,  in  particular,  Ada’s  lack  of  polymor¬ 
phism,  this  proliferation  of  types  can  result  in  cumbersome  programming  requirements. 
There  are  parts  of  many  applications  in  which  abstract  and  strong  typing  are  hindrances. 
These  are  the  parts  of  the  application  which  lie  at  low  levels  of  abstraction.  Examples  are 
communication  protocols  and  display  handlers.  These  services  treat  their  operands  as  bit 
streams  or  character  strings,  not  as  Weights  or  Names  or  Part  Numbers.  It  is  possible,  and 
may  be  desirable,  to  build  abstract  interfaces  to  these  services  for  the  application.  Indeed, 
the  SAME  builds  just  such  abstract  interfaces  for  database  services.  These  interfaces  are 
the  subject  of  the  next  section.  Whether  abstract  interfaces  taking  operands  of  abstract 
types  are  desirable  for  other  services  is  a  matter  for  the  application  designer  to  decide.  It 
should  be  noted,  however,  that  such  interfaces  merely  postpone  the  problem,  moving  it  from 
the  realm  of  the  application  to  the  realm  of  the  implementation  of  the  interface.  This  can 
itself  be  considered  an  advantage;  it  is  considered  an  advantage  of  the  SAME. 

There  are  uses,  other  than  the  operands  of  low-level  interfaces  to  low-level  services,  for 
operands  of  concrete  types.  The  result  of  an  SQL  count  function,  for  example,  often  has  no 
obvious  abstract  type.  Such  values  are  inherently  comparable;  it  makes  perfect  sense  to 
ask  whether  there  aie  more  suppliers  in  Pittsburgh  than  there  are  red  parts  weighing  more 
than  one  ton.  (It  may  not  be  a  very  interesting  question,  but  it  is  well  defined).  It  makes  no 
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sense  to  ask  whether  "Acme’s"  supplier  number  is  greater  than  the  part  number  of 
"Widgets."  Part  numbers  and  supplier  numbers  are  incomparable. 

Highly  generalized  applications  are  similar  to  very  low-level  applications  in  that  they  are  un¬ 
concerned  with  the  specific  semantics  of  the  data  they  manipulate.  The  classic  examples  of 
such  generalized  applications  are  ad  hoc  browsing  programs.  Such  programs  can  be  written 
to  be  independent  of  the  database  schema;  hence,  they  are  necessarily  independent  of  the 
database  semantics.  Applications  such  as  these  are  discussed  in  Chapter  9. 

There  is  yet  another  need  for  concrete  types  in  application  programs.  Certain  of  the  func¬ 
tions  described  in  previous  subsections,  the  Image  and  Value  functions  of  integer  types  and 
the  conversion  functions  for  decimal  types,  have  operands  defined  in  the  base  packages. 
The  application  may  need  visibility  to  the  base  type  for  an  Ada  explicit  type  conversion. 

These  problems  could  be  solved  by  making  the  base  and  concrete  type  packages,  e.g., 
SQL_Standard,  SQL_lnt_Pkg,  etc.,  visible  to  the  application  program.  However,  this  results 
in  inconsistencies  in  the  set  of  functions  of  available  to  the  applications.  The  types  defined  in 
SQL_Standard  are  not  parts  of  any  abstract  domain.  Only  the  Ada  predefined  operators  ex¬ 
ist  for  them.  The  types  defined  in  a  base  type  support  package  have  sets  of  subprograms 
defined  for  them  which  are  slightly  different  from  those  in  an  abstract  domain  package;  the 
differences  are  the  subprograms  generated  by  the  package  instantiation  that  is  part  of  an 
abstract  domain  definition.  Furthermore,  the  naming  conventions  for  these  types  is  slightly 
different  from  the  naming  conventions  for  abstract  domain  types.  To  insure  consistency  in 
accessing  database  values,  application  programs  must  view  all  database  values  through 
some  abstract  domain.  What  is  needed  is  an  abstract  domain  package  which  creates  con¬ 
crete  domains.  The  package  SQL_Bace_Types_Package  is  designed  to  meet  this  need.  It 
appears  in  Figure  3-8. 

Notice  that  the  character  and  decimal  domains  in  Figure  3-8  do  not  contain  constrained  sub- 
types.  Abstract  domains  which  define  database  columns  are  constrained,  since  SQL  charac¬ 
ter  strings  are  fixed  length  and  decimal  values  have  fixed  scale,  given  by  the  SQL  column 
definition.  Objects  of  the  types  in  SQL_Base_Types_Pkg  are  'ess  specific  ana  more 
generalized  or  concrete.  Thus,  these  objects  may  have  any  length  or  scale. 

The  subtype  declarations  which  do  appear  in  Figure  3-8  serve  a  different  function.  They  are 
defined  to  be  the  same  types  as  are  defined  in  the  base  packages.  No  operations  are  de¬ 
fined  within  SQL_Base_Types_Pkg  for  these  subtypes;  therefore,  applications  with  visibility 
to  SQL_Base_Types_Pkg  do  not  have  visibility  to  the  base  operations,  but  only  to  the 
operations  for  the  types  defined  in  that  package.  The  subtypes  can  be  used  as  the 
typemarks  in  an  Ada  explicit  type  conversion.  The  type  of  the  operand  of  those  conversions 
must  be  derived  from  the  same  base  type.  Section  5.6.2  illustrates  the  use  of  those  type 
conversions. 
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With  SQL_Char_Pkg,  SQL_Int_Pkg,  SQL_Smallint_Pkg,  SQL_Raal_Pkg , 
SQL_Double_Praciaion_Pkg,  SQL_Dacimal_Pkg,  SQL_Standaxd; 
package  SQL_B?sa  Typa6_Pkg  is 

package  Charactar_Sat  ranuiac  SQL_Standard. Charactar_Set; 

type  SQL_Int_Not_Null  is  new  SQL_Int_Pkg . SQL_Int_Not_Null; 
type  SQL_Int_Typa  is  new  SQL_Int_Pkg.SQL_Int; 
package  SQL_Int_Opa  is  new  SQL_Int_Pkg.SQL_Int_Opa ( 

SQL_Int_Typa ,  SQL_Int_Not_Null) ; 

Subtype  SQL_Int_Subtypa  is  SQL_Int_Pkg.  SQL_Int; 

subtype  SQL_Int_Not_Null_Subtypa  is  SQL_Int_Pkg .  SQL_Int_Not_Null; 

type  SQL_Smallint_Not_Null  Is  new  SQL_Sraallint_Pkg.SQL_Smallint_Not_Null; 
type  SQL_Smallint_Typa  is  new  SQL_Smallint_Pkg .  SQL_Smallint; 
package  SQL_Smallint_Opa  is  new  SQL_Smallint_Pkg.SQL_Smallint_Opa  ( 
SQL_Smallint_Typa ,  SQL_Smallint_Not_Null) ; 

Subtype  SQL  Smallint_Subtypa  is  SQL_Sraallint_Pkg . SQL_Smallint; 

SUbtype  SQL_Smallint_Not_Null_Subtypa  Is 

SQL_Smallint_Pkg .  SQL_Smallint_Not_Null; 

type  SQL_Real_Not_Null  is  new  SQL_Raal_Pkg.SQL_Raal_Not_Null; 
type  SQL_Raal_Typ«  Is  new  SQL_Raal_P  kg . SQL_Raal ; 
package  SQL_Raal_Opa  Is  new  SQL_Raal_Pkg.SQL_Raal_Opa  ( 

SQL_Raal_Typa ,  SQL_Raal]_Not_Null)  ; 

Subtype  SQL_Raal_Subtypa  is  SQL_Raal_Pkg. SQL_Raal; 

subtype  SQL_Raal_Not_Null_Subtypa  is  SQL_Raal_Pkg  .  SQL_Raal_Not_Null  ; 

type  SQL_Doubla_Praciaion_Not_Null  is 

new  SQL_Doubla_Praciaion_Pkg . SQL_Doubla_Pracision_Not_Null ; 
type  SQL_Doubla_Praciaion_Typa  is 

new  SQL_Doubla_Preciaion_Pkg .  SQL_Double_Pracicic>r>; 
package  SQL_Doubla_Praciaion_Opa  is 

new  SQL_Doubla_Praciaic.n_Pkg.SQL_Doubla_Praci*ion_Opa  ( 

SQL_Doub  la_P  racial on_Typa , 

SQL_Doubla_Praciaion_Not_Null) ; 

Subtype  SQL_Doubla_Praciaion_Subtypa  is 

SQL_Doubla_Praciaion  Pkg . SQL_Doubla_Praciaion; 
subtype  SQL_Doubla_Praciaion_Not_Null_Subtypa  is 

SQL_Doubla  Praciaion  Pkg . SQL_Doubla_Praciaion_Not_Null ; 

type  SQL_Chax_Not_Null  is  new  SQL_Char_Pkg  .  SQL_Char_Not_Null  ; 
type  SQL_Char_Typa  is  new  SQL_Char_Pkg . SQL_Char; 
package  SQL_Char_Op»  is  new  SQL_Char_Pkg .  SQL_Chax_Opa  ( 

SQL_Char_Typa ,  SQL_Char_Not_Null) ; 
subtype  SQL_Char_Subtypa  is  SQL_Char_Pkg .  SQL_Char; 

Subtype  SQL_Cfaar_Not  Hull  Subtypa  is  SQL_Char  Pkg . SQL_Char_Not_NulJ ; 

type  SQL  Dacimal_Not_Nu.ll  is  new  SQL_Daciraal_Pkg .  SQL_Dacimal_Not_Null; 
type  SQL_Dacimal_Typa  is  new  SQL_Dacimal_Pkg . SQL_Dacimal; 
package  SQL_Dacimal_Opa  is  new  SQL_Dacimal_Pkg .  SQL_Dacimal_Opa  ( 
SQL_Dacimal_Typa ,  SQL_Dacimal_Not_Null ) ; 

Subtype  SQL_Dacimal_Subtypa  is  SQL  Dacimal  Pkg.  SQL_Dacimal; 

SUbtype  SQL_Dac i ma i _N ot  Null_Subtypa  is 

SQL_Dacimal_Pkg . SQL_Dacimal_Not_Null ; 

end  SQL  Baaa_Typaa_Pkg; 

Figure  3-8:  The  Package  SQL_Base_Types_Pkg 
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4.  The  SAME  Operational  Model 

The  previous  sections  specify  the  data  definition  process  within  the  SAME.  That  process 
results  in  a  description  of  the  database  contents  in  Ada  terms,  thereby  allowing  the  Ada 
programmer  to  manipulate  database  data  under  the  control  of  Ada's  strong  typing  paradigm. 
The  Ada  descriptions  do  not  require  any  conversions  of  data  representation  and  the  treat¬ 
ment  of  incomplete  information  prevents  any  use  of  null  values  as  though  they  were  not  null. 

This  chapter  describes  the  construction  of  abstract  interfaces  and  abstract  modules. 
Whereas  the  data  definitions  are  used  by  all  applications,  an  abstract  interface  and  its  imple¬ 
mentation,  an  abstract  module,  are  specific  to  a  given  set  of  applications. 

Applications  implemented  using  the  SAME  divide  the  problem  into  two  parts:  the  part  to  be 
solved  in  Ada  and  the  part  to  be  solved  in  SQL  The  SQL  portion  of  the  solution  is  a  collec¬ 
tion  of  procedures  the  bodies  of  which  are  individual  SQL  statements.  This  collection  is 
called  a  module  in  ANSI  standard  SQL  [2],  In  the  SAME,  it  is  called  a  concrete  module,  to 
distinguish  it  from  the  abstract  module  which  the  Ada  programmer  sees. 


4.1 .  Constructing  an  Abstract  Interface 

For  expository  purposes  it  suffices  to  think  of  an  abstract  interface  as  a  package  specifi¬ 
cation  and  an  abstract  module  as  a  package  body.  In  practice  it  is  frequently  advantageous 
to  construct  an  abstract  interface  as  a  collection  of  packages.  The  concrete  interface  is  the 
Ada  package  specification  of  the  SQL  concrete  module.  It  should  be  noted  that  the  ANSI 
standard  requires  that  there  be  only  one  concrete  module  in  any  application  program  ( [2] 
Section  4.8). 

The  abstract  interface  contains  two  kinds  of  declarations:  declarations  of  row  record  types 
and  declarations  of  procedures.  The  procedure  declarations  of  the  abstract  interface  are  one 
for  one  with  the  procedures  of  the  concrete  module.  For  each  SQL  statement  in  the  concrete 
module  there  is  a  procedure  declaration  in  the  abstract  interface  and,  in  the  body,  a  call  to 
that  SQL  statement. 

A  higher  level,  more  abstract  and  application-oriented  interface  than  that  of  the  abstract  in¬ 
terface  is  conceivable.  The  application  designer  may  very  well  wish  to  create  such  an  addi¬ 
tional  layer  that  defines  such  an  interface  for  his  application.  The  SAME  abstract  interface 
does  not  attempt  to  “improve"  SQL.  An  abstract  module  should  deal  only  with  the  details  of 
database  interaction  and  should  never  contain  application  logic. 

A  procedure  declared  in  the  abstract  interface  has  a  parameter  profile  which  differs  from  that 
of  the  procedure  in  the  concrete  interface  that  it  calls.  Parameters  declared  in  the  concrete 
interface  have  types  defined  in  the  package  SQL_Standard  (see  Figure  2-2,  [5],  [16]).  The 
types  of  parameters  and  parameter  components  of  procedures  declared  in  the  abstract  in¬ 
terface  are  the  abstract  types  described  in  the  previous  sections  of  these  guidelines. 

Beyond  that  change  are  two  other  significant  differences  in  the  parameter  profiles  of  proce¬ 
dures  at  the  concrete  and  abstract  interfaces. 

1 .  At  the  abstract  interface,  rows  being  returned  from  the  database  or  inserted 
into  it  are  transmitted  as  record  objects  rather  than  individual  fields.  These 
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records  are  called  row  records  and  their  types  are  the  row  record  types 
declared  in  the  abstract  interface.  Every  component  of  the  record  type  must 
have  its  value  set,  either  in  the  abstract  module  or  in  the  application  program, 
as  appropriate.  In  the  case  of  data  being  transmitted  from  the  database  tc  the 
program,  i.e.,  from  an  SQL  fetch  or  select  statement,  the  components  of  the 
row  record  type  are  one  for  one  with  the  elements  of  the  <target  list>  of  the 
statement.  Similar  comments  apply  to  the  insert  ...  values  SQL  statement. 

2.  The  SQLCODE  parameter  does  not  appear  at  the  abstract  interface.  An  op¬ 
tional  result  parameter  appears  instead.  A  full  description  of  this  parameter 
can  be  found  in  Section  4.3. 

For  concreteness,  Figure  4-1  lists  each  executable  statement  of  ANSI  Standard  SQL  [2]  and 
gives  the  parameters  such  statements  take  as  abstract  procedures  along  with  the  parameter 
modes.  Parameters  listed  as  having  mode  In  out  are  logically  out  parameters  of  a  limited 
type.  (They  are  row  records  whose  components  will  be  of  limited  types.)  Each  such  proce¬ 
dure  may  also  take,  in  addition  to  those  listed,  a  result  parameter  as  the  last  parameter.  The 
result  parameter's  mode  is  always  out.  The  phrase  Individual  Parameters  indicates  that  the 
sequence  of  individual  parameters  in  the  concrete  SQL  module  interface  appea-s  as  a  se¬ 
quence  in  the  abstract  interface,  albeit  with  different  types.  This  treatment  is  usee  primarily 
for  runtime  parameters  of  SQL  where  and  having  clauses.  Notice  that  only  the  select  state¬ 
ment  may  take  both  a  row  record  (for  the  retrieved  row)  and  a  sequence  of  individual 
parameters  (for  the  where  or  having  clause). 


SQL  Statement 

Ada  Parameter  Kinds 

Mode 

close 

none 

commit 

none 

delete  -  positioned 

none 

delete  -  searched 

Individual  Parameters 

in 

fetch 

row  record 

In  out 

insert  values 

row  record 

in 

insert  (subquery) 

Individual  Parameters 

in 

open 

Individual  Parameters 

in 

rollback 

none 

select 

row  record 

in  out 

Individual  Parameters 

in 

update  -  positioned 

Individual  Parameters 

in 

update  -  searched 

Individual  Parameters 

in 

Figure  4-1:  Parameter  Kinds  (with  Modes) 


4.1.1.  A  Note  on  Typing  Parameters 

It  should  not  generally  be  difficult  to  determine  the  types  of  the  individual  parameters  and 
row  record  components  at  the  abstract  interface.  If  the  values  of  that  parameter  or  compo¬ 
nent  are  in  transit  between  the  application  program  and  a  database  column  or  are  compared 
to  a  database  column  in  a  where  or  having  clause,  the  type  to  be  used  is  one  of  the  ab¬ 
stract  types  describing  the  abstract  domain  underlying  that  column.  If  the  null  value  is  per¬ 
missible  in  the  given  context,  a  type  supporting  null  values  must  be  used. 
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In  the  case  that  the  value  involved  is  the  result  of  an  expression  in  the  SQL  statement,  par¬ 
ticularly  one  involving  more  than  one  database  column,  the  appropriate  abstract  type  may 
not  be  obvious.  It  may  be  necessary  and  desirable  to  create  a  new  type  for  such  an  expres¬ 
sion  (see  Section  3.7).  The  class  of  that  abstract  type,  e.g.  <wt  opal,  etc  ,  can  be  estab¬ 
lished  from  the  concrete  type  of  the  parameter  that  holds  values  of  the  expression  at  the 
concrete  interface.  The  general  problem  of  typing  parameters  whose  values  are  set  by  SQL 
expressions  is  an  instance  of  the  “dimensional  analysis”  problem.  The  SAME  does  not  pro¬ 
vide  its  own  solution  to  that  problem. 

Example 

Consider  the  following  problem:  “Calculate  the  total  weight  of  all  orders  for  a  given  part 
number."  The  SQL  module  specification  for  this  query  is: 

MODULE  Concrete _ Mod 

LANGUAGE  Ada 


Procedure  Calculate_Weight 
PNUMBER  Char (5) 

Total_Weight  Int 
TW_Indic  Smallint 
SQLCODE; 

■elect  *um(QTY  *  WEIGHT) 

into  Total_Weight  INDICATOR  TW_Indic 

from  P ,  SP 

where  P.PNO  =  SP.PNO 
and  P.PNO  =  PNUMBER; 

The  concrete  interface,  that  is,  the  Ada  specification  of  that  SQL  module  is: 

With  SQL_Standard;  use  SQL_Standard; 
package  Concrete_Mod  is 

procedure  Calculate_Weight  (PNUMBER  :  Char; 

Total_Weight  :  out  Int; 

TW_Indic  out  Indicator  Type; 
SQLCODE  :  OUt  SQLCODE_Type ) ; 


end  Concrete  Mod; 

The  abstract  interface  for  this  procedure  (without  the  package  declaration  and  context 
clauses  and  assuming  no  result  parameter)  is: 

type  Weight_Record  is  record 
Total  :  Weight_Type; 
end  record; 


procedure  Calculate_Weight  (PNUMBER  :  in  PNO_Not_Null ; 

Weight :  in  Out  Weight_Record) ; 

In  this  case,  the  expression  clearly  results  in  a  Weight,  an  abstract  domain  already  identi¬ 
fied.  For  uniformity,  a  row  record  is  used  for  the  output,  even  though  the  record  contains 
only  one  component.  The  type  of  the  component  must  allow  tor  nulls,  that  is,  must  be 
Weight_Type  rather  than  Weight_Not_Null,  since,  if  PNUMBER  is  not  the  number  of  some 
part  for  which  some  orders  are  recorded  in  SP,  the  result  of  this  query  is  the  null  value  ( [2] 
Section  5.8,  general  rule  4.c). 
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4.1.2.  A  Note  on  Naming  and  Packaging 

The  SAME  does  not  mandate  any  specific  packaging  of  abstract  interface  procedures.  As 
mentioned,  the  rules  of  SQL  require  the  concrete  interface  to  be  a  single  package.  The  ab¬ 
stract  interface  can  be  partitioned  as  fits  the  needs  of  the  application.  To  prevent  unnec¬ 
essary  recompilations,  the  concrete  interface  should  be  imported  into  the  context  of  the 
bodies,  not  the  specifications,  of  the  abstract  module  packages. 

In  general,  the  SAME  does  not  specify  the  names  of  the  procedures  at  the  abstract  interface 
nor  the  names  of  their  parameters.  This  naming  is  the  responsibility  of  the  application 
builder.  However,  the  SAME  suggests  that  the  set  of  procedures  associated  with  a  given 
cursor  declaration,  the  open,  fetch,  close  and  if  needed,  positioned  update  and  delete 
procedures,  be  placed  in  a  separate  package  or  subpackage  of  the  abstract  interface.  The 
name  of  the  package  can  be  the  name  of  the  cursor.  The  open  procedure  for  a  given  cursor, 
for  example,  is  then  referred  to  as  cursor_name.open. 


4.2.  Constructing  an  Abstract  Module 

The  bodies  of  the  procedures  declared  in  the  abstract  interface  form  the  abstract  module. 
Each  of  these  procedure  bodies  has  much  the  same  form. 

1 .  The  concrete  module  procedure  is  called. 

2.  The  status  code  field  (SQLCODE)  is  processed  according  to  the  procedures 
described  in  Section  4.3. 

3.  Type  conversions  are  applied  to  the  parameters  at  the  concrete  interface, 
transforming  them  to  objects  of  the  types  at  the  abstract  interface. 

For  procedures  that  take  input  parameters,  step  3  occurs  first  and  in  the  other  direction.  If  a 
procedure  takes  no  parameters,  step  3  does  not  occur  at  all.  The  type  conversions  of  step  3 
generally  take  the  form  of  a  test  for  null,  followed  by  an  Assign  procedure  call. 

Example 

The  body  of  the  procedure  Calculate_Weight  (of  the  prior  example)  is  displayed  in  Figure 
4-2,  with  the  package  declarations  and  context  clauses  omitted  for  brevity. 

The  input  parameter,  PNUMBER,  must  be  converted  to  a  type  (Char)  defined  in 
SQL_Standard,  using  an  Ada  explicit  type  conversion.  Had  PNUMBER  had  type 
PNO_Type,  a^call  to  Without_Null  would  be  necessary  and  Null_Value_Error  might  be 
raised.  The  concrete  module,  as  given  earlier,  made  no  provision  for  null  values  in  PNUM¬ 
BER,  there  being  no  INDICATOR  for  it.  The  raising  of  an  exception  here  conforms  to  ANSI 
specifications  Database  Language  -  SQL,  Sections  8.6  and  8.10,  general  rule  8)  for  this 
situation. 

The  processing  of  the  output  is  typical.  A  negative  indicator  value  indicates  a  null  value.  A 
non-null  value  must  be  transformed,  using  an  explicit  Ada  type  conversion,  from  a  type  in 
SQL_Standard  (in  this  case,  Int),  to  the  _Not_Null  type  and  then,  if  necessary,  to  the  output 
type,  via  With_Null. 
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procedure  Calculate_W«ight  (PNCMBER  :  in  PNO_Not_Null ; 

Weight  in  out  Weight_Record)  is 
Weight  Indie  :  SQL  Standard . Indicator  Type; 

Weight_Buf fer  ;  SQL_Standard . Int ; 
begin 

Concrete_Mod . Calculate  Weight  ( 

SQL_St  an  dar d . Char (PNUMBER) , 

Weight_Buf f <r, 

Weight_Indic, 

SQL_Communicatione_P)tg .  SQLCODE)  ; 
if  SQL_ConBnunication«_Pkg .  SQLCODE  /=  0  then 
<«*e  section  4.3> 

end  if; 

if  Weight_Indie  <  0  then 

assign (Weight . Total ,  Null_SQL_Int ) ; 

else 

assign (Weight . Total , 

With_Null (Weight_Not_Null (Weight_Buffer) ) ) ; 
end  Calculate_Weight; 

Figure  4-2:  The  Abstract  Module  Procedure  Calculate_Weight 


4.3.  Database  Exceptional  Conditions 

Every  database  interaction  is  capable  of  failing.  Application  programmers  frequently  forget 
this,  and  assume  that  some  database  interaction  will  always  succeed.  Frequently,  they  as¬ 
sume  that  a  given  interaction  can  fail  in  one  of  a  small  set  of  predictable  ways  (e.  g.,  no 
record  found)  and  forget  to  check  for  unpredictable,  unrecoverable  failures  (e.  g.,  disk 
errors).  The  net  result  is  that  in  the  presence  of  failure,  the  application  program  behaves  in 
ways  that  cannot  be  predicted  or  analyzed.  The  SAME  provides  a  robust  treatment  of  data¬ 
base  exceptional  conditions  which  allows  the  average  application  to  assume  a  failure  free 
database  while  allowing  more  sophisticated  applications  the  freedom  to  do  their  own  error 
recovery. 

ANSI  standard  SQL  systems  signal  the  presence  of  an  exceptional  condition  through  a 
status  parameter  called  SQLCODE.  The  values  of  this  parameter  are  not  set  by  the  stan¬ 
dard  and  therefore  differ  from  implementation  to  implementation.  The  number  of  distinct  er¬ 
ror  values  is  usually  in  the  hundreds.  The  overwhelming  majority  of  these  values  signal  fatal 
errors  from  which  the  average  application  will  not  be  able  to  recover.  The  SAME  is  oriented 
to  the  needs  of  such  an  average  application. 

The  following  steps  constitute  the  treatment  of  database  exceptional  conditions  in  the 
SAME: 

1.  As  each  SQL  statement  is  designed  and  written  for  the  application  program, 
the  set  of  DBMS  error  conditions  which  the  application  will  tolerate  must  be 
identified.  In  the  most  frequently  occurring  cases,  this  set  will  either  be  empty 
or  will  be  the  singleton  “no  record  found"  condition. 

2.  If  the  set  identified  in  the  prior  step  is  not  empty,  the  abstract  interface  specifi¬ 
cation  of  the  procedure  that  executes  that  statement  will  include  the  optional 
result  parameter.  That  parameter  has  an  enumeration  type,  frequently,  but  not 
necessarily,  boolean,  if  the  application  is  sensitive  to  failure  but  not  to  failure 
mode  (or  in  the  case  that  the  set  identified  above  is  a  singleton),  a  Boolean  is 
sufficient.  The  mapping  of  status  code  values  to  enumeration  values  must  be 
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determined.  (For  example,  a  “no  record  found"  condition  returned  from  a 
delete  may  bt  considered  a  successful  termination.) 

3.  The  body  of  this  procedure  in  the  abstract  module  body  will  then,  upon  return 
from  the  concrete  procedure,  examine  the  SQLCODE  variable  (see  Section 
4.3.1).  The  value  of  the  result  parameter  is  set  correctly,  in  the  case  of  suc¬ 
cess  or  of  a  fail'. re  mode  anticipated  in  the  set  described  above.  In  the  case  of 
a  failure  mode  outside  that  set,  the  procedure  Process_Database_Error 
declared  in  package  SQL_Database_Error_Pkg  is  called  and  the  exception 
SQI__Database_Error  declared  in  SQL_Communications_Pkg  is  raised. 

This  treatment  allows  the  application  programmer  to  ignore  exceptional  database  conditions 
that  are  not  germane  to  the  application  and  from  which  it  cannot  recover.  Raising  an  exce' 
tion  makes  the  condition  difficult,  although  not  impossible,  to  ignore.  When  desired,  an  error 
recovery  routine  can  be  coded  as  a  handler  for  the  SQL_Database_Error  exception. 

4.3.1.  The  Packages  SQL_Communications_Pkg  and 
SQL_Database_Error_Pkg 

The  SAME  standard  packages  SQL_Communications_Pkg  and  SQL_Database_Error_Pkg 
support  the  authors  of  abstract  modules  and  of  those  applications  which  do  more  sophis¬ 
ticated  error  recovery  processing.  The  specification  of  these  packages  can  be  found  in 
Figure  4-3.  Both  of  these  packages  must  be  tailored  by  the  user.  The  specifications  in 
Figure  4-3  are  the  basic  skeletons,  which  may  be  modified  as  needed. 

SQL_Communications_Pkg  is  specific  to  the  platform;  it  must  be  tailored  to  the  specific 
DBMS  in  use  at  a  site.  There  need  be  only  one  copy  of  SQL__Commumcations_Pkg  at  a  site. 
SQL_Database_Error_Pkg  is  specific  to  the  application.  There  may  be  more  than  one  copy 
of  this  package  at  a  site.  In  the  most  likely  case,  many  applications  will  share  a  copy  of 
SQl_Database_Error_Pkg.  The  package  is  best  described  as  being  specific  to  an  applica¬ 
tion  class. 

Every  module  language  procedure  must  contain  an  <sqlcode  parameter  ( Database  Lan¬ 
guage  -  SQL,  Section  7.3,  syntax  rule  6).  The  call  to  each  concrete  module  procedure  from 
each  abstract  module  procedure  uses  the  global  variable  SQLCODE  declared  in  the  specifi¬ 
cation  of  Sql_Communications_Pkg.26  Given  the  importance  of  the  status  code,  it  is  best  not 
to  duplicate  it  unnecessarily  as  that  could  lead  to  confusion  over  which  copy  is  current. 

(Only  the  most  recent  value  of  the  status  code  is  of  interest.) 

The  procedure  Process_Database_Error  should  perform  whatever  processing  must  be  done 
before  the  exception  is  raised  and  information  is  lost.  This  procedure  should  not  attempt 
error  recovery.  That  should  be  done  by  the  exception  handler.  Rather,  this  procedure 
gathers  whatever  information  will  be  needed  by  the  recovery  mechanism.  It  is  legitimate, 
and  probably  desirable,  for  Process_Database_Error  to  initiate  a  transaction  rollback.  For 
that  to  be  the  case,  the  procedure  must  be  able  to  find,  (that  is  know  the  name  of)  a  sub¬ 
program  that  will  cause  the  SQL  rollback  work  command  to  be  executed. 


^Most  DBMSs  define  a  communications  area  which  includes  a  good  deal  of  information  beyond  SQLCODE. 
The  SAME  allows  for  modifications  of  the  specification  of  SQL_Communications_Pkg  to  include  that  information 
Populating  those  variables  with  data  is  a  DBMS-specific  task,  not  covered  by  the  SAME. 
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SQL_Communications_Pkg 

With  SQL_Char_Pkg,  SQL_Standard; 
use  SQL_Char_Pkg,  SQL_Standaxd; 
package  SQL_Coromun.i  cation*  Pkg  is 

SQL_Database_Error  :  exception; 

SQLCODE  :  SQLCODE  JTYPE ;  —  Global  variabla 

—  paxamstarlsss  function  returning  an  error  message  of  type 

SQL_Ch*r_Not_Null 

—  the  error  message  is  the  descriptive  string  associated  with 

—  the  most  recent  database  error 

function  SQL_Database_Error_Message  return  SQL_Char  Not  Null; 
end  SQL  Communications  Pkg; 


SQL_Database_Error_Pkg 


package  SQL_D*taba*e_Error_Pkg  is 

—  The  following  procedure  must  be  present  in  every  version  of 
—  SQL_Database_Error_Pkg .  It' s  purpose  is  to  perform  standard 

—  processing  of  unexpected  exceptional  conditions.  It  should  not 

—  attempt  error  recovery. 

procedure  Process_Database_Error; 
end  SQL_!>»tab»»«_Error_Pkg; 


Figure  4-3:  Package  Specifications  for  Sql_Communications_Pkg  and 

SQL_Database_Error_Pkg 

In  the  most  frequently  occurring  case,  there  will  be  no  handler  for  the  SQL_Database_Error 
exception.  The  exception  is  raised  only  when  an  exceptional  condition  from  which  the  appli¬ 
cation  cannot  recover  arises.  Generally,  this  indicates  either  a  programming  error  or  a  cor¬ 
ruption  of  the  database  Manual  intervention  will  usually  be  required  to  repair  the  condition 
that  caused  the  exception  to  be  raised.  The  purpose  of  Process_Database_Error  is  to  dis¬ 
play  a  suitable  error  message  on  a  suitable  device  or  devices  so  that  the  nature  of  the  error 
will  be  known.  The  choice  of  device  may  depend  upon  the  class  of  an  application.  Batch 
applications  may  wish  to  notify  the  system  operator,  record  the  message  in  an  error  log  and 
place  a  copy  into  the  standard  application  output  file.  Online  applications  may  do  all  of  those 
things  and  also  notify  the  terminal  user. 

Most  SQL  DBMSs  provide  a  routine  that  converts  an  SQLCODE  value  into  a  meaningful 
message.  The  function  SQL_Database_Error_Message  in  SQL_Communications_Pkg  is 
meant  to  interface  to  that  routine.  As  the  ANSI  standard  does  not  include  this  functionality, 
the  body  of  this  function  must  be  tailored  to  the  DBMS. 
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4.3.2.  Handler  for  SQL_Database_Error 

Applications  which  mus.  be  fault  tolerant,  and  applications  written  in  accordance  with  local 
standards  prohibiting  unhandled  exceptions,  will  provide  exception  handlers  for  the 
SQL_Database_Error  exception.  These  handlers  typically  appear  fairly  high  in  the  dynamic 
call  structure  of  the  application,  e.g.,  in  a  driver  procedure,  as  they  are  meant  to  deal  with 
errors  that  are  fairly  general  in  nature.  Recall  that  the  exception  handler  deals  only  with  con¬ 
ditions  that  the  application  itself  could  not  process. 

If  an  exception  handler  is  to  be  used  in  an  application,  the  Process_Database_Error  proce¬ 
dure  may  need  to  be  specialized  to  work  cooperatively  with  the  handler.  For  example,  if  the 
procedure  initiates  a  rollback  operation,  the  contents  of  the  global  variable  SQLCODE  at  the 
time  of  failure  will  be  destroyed  by  the  rollback  operation.  It  may  be  that  the  handler,  not 
executed  until  after  the  termination  of  Process_Database_Error,  will  obviate  the  need  for  the 
rollback  by  repairing  the  error.27  The  handler  may  need  information  which  has  been 
destroyed  by  the  exception’s  being  raised.  Process_Database_Error  may  save  such  infor¬ 
mation  for  the  handler's  use.  (It  will  have  to  do  so  either  in  global  variables,  as  its  local 
variables  will  have  been  destroyed  when  the  handler  is  run,  or  by  calling  subprograms 
visible  to  the  exception  handler  which  can  accept  and  store  the  information.)  Specializations 
such  as  these  may  require  modifications  to  the  specifications  of  the  packages 
SQL_Database_Error_Pkg  and  SQL_Communications_Pkg.  This  is  perfectly  acceptable, 
provided  that  the  global  variable  SQLCODE  and  the  procedure  Process_Database_Error 
appear  as  shown  in  Figure  4-3. 

As  has  been  stated,  the  goals  of  the  SAME  treatment  of  the  SQLCODE  status  parameter 
are: 

1.  To  free  the  application  programmer  from  any  concern  with  exceptional  con¬ 
ditions  not  meaningful  to  the  application. 

2.  To  make  the  occurrence  of  such  exceptional  conditions  known  to  the  people 
running  the  application  and  difficult  for  the  application  to  ignore  in  order  to 
prevent  the  eventual  application  failure  from  being  unanalyzable. 

3.  To  allow  fault -tolerant  programs  the  ability  to  recover  from  system  failures. 

It  is  possible  for  a  software  development  organization  to  meet  these  goals  through  the 
promulgation  of  programming  standards.  The  SAME  treatment  of  the  SQLCODE  parameter 
ensures  that  errors  are  handled  in  a  standard  manner  specified  by  the  organization,  without 
the  need  for  standards  enforcement.  This  is  because  the  realization  of  those  standards  lies 
not  with  the  application  programmers,  but  rather  with  the  system  software  designers.  Most 
organizations  should  find  that  they  need  very  few  distinct  copies  of  the  packages  involved  in 
this  processing,  which  can  be  shared  by  the  application  programs. 


^This  seems  unlikely.  More  likely  is  that  an  exception  handler  will  trap  the  exception,  to  prevent  abnormal 
program  termination,  and  allow  the  application  to  restart  (rather  than  recover).  Since  the  underlying  problem  has 
not  been  repaired,  it  may  recur. 
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4.4.  Note  on  the  Overloading  of  INDICATOR  Parameters 

The  primary  purpose  of  indicator  parameters  in  the  SQL  module  language  is  the  indication 
of  null  values.  (See  Database  Language  -  SQL,  Section  4.10.2.)  However,  indicator 
parameters  have  a  secondary  usage,  described  by  general  rule  8. a  of  Sections  8.6  and  8.10 
of  Database  Language  -  SQL: 

[Let  V  be  an  output  parameter  and  v  be  the  non  null  value  to  be  assigned  to  V.]  If 
the  data  type  of  V  is  character  string  of  length  L  and  the  length  M  of  v  is  larger 
than  L,  then  the  indicator  is  set  to  M. 

In  other  words,  indicators  can  be  used  to  inform  the  program  that  a  character  string  has 
been  truncated.  Interestingly,  if  L  in  the  above  is  larger  than  M,  padding  occurs  and  the 
program  is  not  informed. 

Since  the  SAME  uses  Ada’s  abstract  typing  facilities  to  encapsulate  null  values,  it  does  not 
support  indicators  at  the  abstract  interface.  The  SAME-DC  felt  that  the  use  of  indicators 
described  in  the  above  quotation  would  be  of  use  to  only  a  small  fraction  of  all  database 
applications.  A  means  of  satisfying  those  applications  without  penalizing  the  majority  of  ap¬ 
plications  was  developed. 

An  abstract  procedure  that  corresponds  to  a  concrete  fetch  or  select  statement  may 
declare  an  additional  record  parameter.  This  record  will  have  components  all  of  type 
SQL_Standard.lndicator_Type  (or  a  type  derived  from  this,  if  desired).  Each  component  of 
this  indicator  record  corresponds  to  a  string  component  of  the  row  record.  The  name  of  each 
component  in  the  indicator  record  is  the  name  of  the  component  in  the  row  record,  and  they 
appear  in  the  same  order  although  some  string  components  may  be  missing.  The  body  of 
the  abstract  procedure  copies  the  indicator  values  from  the  concrete  indicator  parameters  to 
the  components  of  ine  indicaior  record  for  those  string  components  that  have  indicators. 

The  SAME-DC  felt  that  this  solution  was  the  cleanest  available.  Altering  the  row  record  type 
definitions  to  include  indicators  seemed  inappropriate.  Altering  the  abstract  types, 

SQL_Char  and  SQL_Char_Not_Null,  would  have  penalized  all  applications  to  support  only  a 
few. 
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5.  Notes  on  Writing  Application  Programs  Using  the 
SAME  Method 

This  chapter  contains  hints  and  suggestions  tor  the  designer  and  programmer  using  the 
SAME  for  an  Ada  database  application. 


5.1.  Design  Rules 

The  SAME  method  of  constructing  database  applications  divides  the  problem  into  two  parts: 
the  part  to  be  solved  in  Ada  and  the  part  to  be  solved  in  SQL  A  rule  of  thumb  to  use  in 
determining  this  division  is:  If  a  part  of  the  problem  can  be  solved  in  either  the  Ada  or  the 
SQL  portion  of  the  application,  solve  it  in  SQL.  The  rationale  for  this  rule  is  that  the  more  the 
database  management  system  knows,  the  more  it  can  optimize  its  behavior.  For  example, 
suppose  an  application  is  interested  in  all  “red”  parts.  It  is  possible  to  write  an  SQL  state¬ 
ment  which  returns  all  parts  and  an  Ada  program  which  finds  the  red  ones.  However,  it  is 
also  possible  to  write  an  SQL  statement  which  returns  only  rod  parts.  In  that  case,  at  the 
very  least,  there  will  be  fewer  calls  from  the  Ada  application  to  the  DBMS  at  runtime.  If  an 
index  on  COLOR  exists  in  the  database,  the  total  runtime  can  be  drastically  reduced. 


5.2.  Visibility  and  the  Use  of  use 

The  application  program  will  need  visibility  to  the  domain  packages  that  define  the  relevant 
types  and  to  the  abstract  interface.  The  domain  packages  have  been  designed  to  be  used. 
The  domain  packages  contain  instantiated  subpackages  that  are  likewise  meant  to  be  used. 
This  use  of  use  allows  the  operators  (comparison  and  arithmetic)  defined  in  the  support 
package  to  be  used  in  their  normal  infix  notation.  These  domain  packages  typically  declare, 
either  by  generic  instantiation  or  subprogram  derivation,  numerous  versions  of  subprograms 
with  the  same  name.  Tnese  subprograms  can  be  distinguished  by  their  parameter  profiles 
and  often  can  be  distinguished  only  in  that  way.  Giving  their  complete  names  will  not 
uniquely  identify  them. 

There  is  a  situation  in  which  use  should  not  be  used  in  the  SAME.  If  two  subtypes  of  a  type 
are  declared  in  a  domain  package  and  generic  subpackages  instantiated  for  them,  the  sub¬ 
programs  generated  in  those  subpackages  will  have  the  seme  parameter  profiles.  If  only 
one  of  the  subtypes  is  needed  in  the  application,  it  can  be  used  in  the  normal  way.  How¬ 
ever,  if  both  subpackages  are  used,  they  will  effectively  hide  each  other.  In  this  case,  nei¬ 
ther  subpackage  should  be  used;  subprograms  within  them  should  be  referred  to  as 
<subpackage  name>. subprogram  name>.  Be  careful  to  use  the  correct  subpackage  with 
the  correct  subtype  (see  Section  3.3). 

(The  instantiated  generic  package  which  forms  part  of  the  declaration  of  an  enumeration 
type  abstract  domain  [see  Section  3.6]  L  also  not  meant  to  be  used.  Use  of  the  domain 
package  will  bring  the  derived  function  names  into  scope.) 

Application  programs  should  not  have  visibility  to  any  of  the  SAME  standard  packages.  They 
should  depend  only  on  the  domain  packages  and  abstract  interface  packages  which  have 
been  developed  for  them. 
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5.3.  Using  Non-ASCII  Character  Sets 

The  SAME  support  tor  character  database  columns  is  designed  to  allow  SAME  application 
programs  to  be  portable  across  machines  with  difterent  native  character  sets.  As  a  by¬ 
product,  SAME  applications  can  eliminate  unnecessary  character  set  conversions. 

It  the  character  set  native  to  the  machine  on  wnich  a  SAME  application  is  running  is  not 
ASCII,  then  SQL_Standard.Character_Set  is  not  set  to  Standard. Character  (see  Figure  2-2). 
Rather,  SQL_Standard.Character_Set  is  a  renaming,  that  is  a  subtype,  ot  an  enumeration 
type  which  defines  the  native  character  set.  String  literals  over  that  character  set  can  be 
formed  in  the  normal  way,  provided  that  the  name  of  the  enumeration  type  specifying  the 
character  set  is  in  scope.  The  context  in  wnich  the  literal  appears  must  be  sufficient  to  deter¬ 
mine  which  character  set  is  to  be  used,  since  the  predefined  package  Standard  cannot  be 
taken  out  of  the  scope  of  any  Ada  compilation  unit. 

If,  for  example,  the  host  character  set  is  supported  by  a  package  named 
Host_Character_Pkg,  then  the  application  can  use  Host_Character_Pkg  if  it  needs  to  con¬ 
tain  string  literals  over  the  host  characters.  Let  String_Var  and  String_Var_Not_Null  be  vari¬ 
ables  of  types  derived  from  SQL_Char  and  SQL_Char_Not_Nuil,  respectively.  If  the  name  of 
the  DBMS  character  type  is  in  scope,  then  both 

Equal* (String_Var , With_Null ( "A  String") ) 

and 

String_Var_Not_Null  =  "A  String” 

are  syntactically  correct  and  behave  as  expected. 

If  the  character  set  native  to  a  machine  on  which  a  SAME  application  is  to  De  run  is  ASCII, 
that  is,  if  SQL_Standard.Character_Set  is  SQL_Standard.Char,  then  the  predefined  Ada 
type  stnng  and  the  type  SQL_Char_Not_Null  (and  types  derived  from  it)  are  structurally 
identical  (they  are  both  unconstrained  one  dimensional  arrays  with  the  same  component 
type),  and  are  interconvertible  using  Ada  explicit  type  conversions,  if  such  conversions  are 
used,  however,  the  resulting  code  is  not  portable  to  a  machine  whose  native  character  set  is 
not  ASCII.  The  functions  To_String  (and  To_Unpadded_String)  and 
To_SQL_Char_Not_Null  (and  To_SQL_Char)  are  modified  at  the  time  of  SAME  software 
installation  to  make  them  aware  of  the  native  character  set  and  to  properly  perform  the  type 
conversion.  Use  of  these  functions  exclusively  for  the  purpose  or  sucn  conversions  results  in 
an  application  that  is  portable  across  machines  with  different  character  sets.  However,  one 
further  step  is  needed  to  complete  this  portability.  If  the  advice  given  to  use 
Hos^Character  Pkg  to  enable  string  literal  formation  is  followed,  the  resulting  code  will  not 
compile  on  a  machine  whose  native  character  set  is  ASCII  and  on  which,  presumably, 
Host_Character_Pkg  does  not  exist.  To  ensure  correct  behavior  on  both  ASCII  and  non- 
ASCII  machines,  the  program  should  use  the  package  SQL_Standard.Character_Set. 
SQL_Standard  is  not  meant  to  be  visible  to  application  programs.  The  package 
SQL_Base_Types_Pkg  describee  in  Section  3.8  contains  a  renaming  declaration  of  that 
package.  Therefore,  a  character  set  independent  program  should  use 
SQL_Base_Types_Pkg.Character_Set  to  enable  formation  of  literals  of  types  derived  from 
SQL_Char_Not_Nuil. 

Altnough  one  speaks  of  a  given  machine's  native  character  set,  it  is  neither  the  CPU  nor  the 
magnetic  storage  media  that  are  sensitive  to  character  set  encodings.  These  encodings  are 
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properties  of  the  display  devices,  printers,  and  terminals  attached  to  the  system.  In  many 
DBMS  applications,  haracter  strings  are  retrieved  from  the  database  and  displayed  on  a 
display  device,  often  without  being  examined  by  the  software,  it  is  highly  inefficient  to  con¬ 
vert  such  data  from  the  native  character  set  to  ASCII  as  the  data  is  read  from  the  database, 
and  then  from  ASCII  to  the  native  character  set  as  the  data  is  displayed  on  the  output  de¬ 
vice.  The  conversion  is  time-consuming  and  does  nothing  to  forward  the  application’s 
progress.  If  all  character  string  variables  within  an  application  are  of  types  derived  from 
SQL_Char_Not_Null  (or  SQL_Char),  those  conversions  will  not  occur.28 


5.4.  Handling  the  Null  Value  Error  Exception 

The  exception  Null_Value_Error  is  raised  by  subprograms  of  the  SAME  standard  packages 
when  an  invalid  use  of  a  null  value  is  detected.  Typically,  this  is  an  attempt  to  convert  the 
null  value  to  a  type  which  does  not  support  nulls.  The  exception  is  defined  in  the  SAME 
standard  package  SQL_Exceptions.  In  order  to  provide  a  handler  for  that  exception,  the 
package  must  be  brought  into  scope. 


5.5.  Simulating  Predefined  Attributes 

The  limited  private  types  which  the  SAME  standard  packages  use  to  simulate  SQL  data 
semantics  have  operations  which  allow  objects  of  those  types,  and  the  types  derived  from 
them  that  appear  in  abstract  domain  declarations  in  domain  packages,  to  appear  very  much 
like  visible  Ada  types.  For  example,  variables  of  the  SQL_Jnt  types  Weight_Type, 
Status_Type,  and  Qty_Type  (see  Figure  3-7)  support  arithmetic  and  comparison  operators 
identical  to  the  Ada  integer  operators  whenever  the  values  of  those  variables  are  not  null. 
Since  the  types  are  limited  private,  however,  the  attributes  predefined  for  integer  types  are 
not  available.  Most  of  the  those  attributes  can  be  simulated. 

Those  attributes  which  are  properties  of  the  type,  rather  than  properties  of  objects  of  the 
type  or  functions  defined  on  objects  of  the  type,  can  be  applied  to  the  _Not_Null  type.  That 
is,  Weight_Type'First  is  not  defined  but  Weight_Not_Null'First  is  defined  and  is  the  smallest 
non-null  value  that  can  stored  in  a  variable  of  type  Weight_Type. 

Many  of  those  attributes  which  are  properties  of  objects  or  functions  on  objects  are  dupli¬ 
cated  by  functions  defined  on  the  limited  private  type.  Examples  of  these  are  Succ,  Pred, 
Image,  and  Value  for  enumeration  types,  and  Image  and  Value  for  integer  types.  The  length 
attribute  for  strings  is  simulated  by  the  discriminant,  Length,  of  the  SQL_Char  type.  Recall 
that  the  discriminant  of  a  limited  type  is  visible  outside  the  package  defining  the  type.  The 
attributes  'Range,  'First,  and  'Last  are  not  simulated  for  SQL_Char,  nor  is  it  possible  to  ac¬ 
cess  individual  characters  of  a  string  object  of  a  type  derived  from  SQL_Char.  Suppose,  for 
example,  some  processing  is  to  be  done  if  a  variable  String_Var,  of  a  null  bearing  type  de¬ 
rived  from  SQL_Char,  contains  the  character  “X."  The  following  code  fragment  is  correct. 


^There  =>re  Ada  contexts  In  which  t:  ..  predefined  type  string  Is  mandatory:  the  subprograms  within  the 
package  TtXTJO  and  the  parameters  of  *he  'Image  and  'Value  attribute  functions.  The  latter  functions  are 
duplicated  by  functions  defined  in  the  SAME  support  software.  The  SAME  does  not  provide  a  rep'-.rement  for 
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for  i  in  1 ..  St ring_Var  .  Langth  loop 

If  Ia_True (Equals (substring (String_V ax , i , 1 ) ) , 

With_Null("X") )  then 
—  procsss  as  needed 

exit; 
end  If; 
end  loop ; 

At  the  expense  of  a  temporary  variable  assignment,  the  above  code  could  be  rewritten  as: 

Sfcring_Var__Not_Null  :=  Without_Null (String_Vax) ; 
for  i  in  String_V»r_Not  Null' Range  loop 
If  String_Var  Not  Null(i)  =  'X'  then 

—  process  as  needed 

exit; 
end  If; 
end  loop ; 

but  this  code  is  correct  only  if  String_Var  is  known  not  to  be  null.  The  original  code  is  cor¬ 
rect,  in  the  sense  that  the  process  is  executed  only  if  String_Var  contains  the  character  "X”, 
in  all  cases.  The  following  version  is  robust  and  more  efficient,  particularly  when  the  string 
of  trailing  blanks  in  String_Var  is  long. 

if  Not_Null  (String_Var)  then 

String_Var_Not_Null  ;=  Without_Null (String_Vax) ; 
for  i  in  1 . . Onpaddsd  Langth (String_Vax)  loop 

--  Sines  String_Var_Not_Null  has  tha  _Not_Null  typs 
—  of  sons  abstract  domain,  String  Var  Not  Null 'First  =  1. 

If  String_Var_Not_Null  (1)  =  'X'  then 
—  procsss  as  nssdsd 
exit; 
end  if; 
end  loop; 
end  if; 

The  extended  example  of  Chapter  8  contains  further  examples  of  this  kind  of  processing. 


5.6.  Doing  Type  Conversions 

It  sometimes  becomes  necessary  in  Ada  programs  to  convert  an  object  from  one  type  to 
another.  This  section  contains  some  details  to  be  kept  in  mind  when  type  converting  data¬ 
base  objects. 

5.6.1.  Ada  Explicit  Type  Conversions 

For  all  domains,  except  those  based  on  a  binary  coded  decimal  (BCD)  concrete  represen¬ 
tation,  the  non-null  bearing  _Not_r‘l  les  are  visible  Ada  types.  Therefore,  type  conver¬ 
sion  for  objects  of  these  types  .  in  the  ordinary  way.  The  null  bearing  _Type  objects 
are  of  a  limited  private  type.  (This  is  also  true  of  the  _Not_Null  decimal  objects.)  Objects  of 
these  types  are  interconvertible  with  other  objects  derived  from  the  same  base  type,  directly 
or  indirectly.  This  is  to  say,  any  object  the  type  of  which  is  based  on  SQLJnt  can  be  con¬ 
verted  by  an  Ada  explicit  type  conversion  to  any  other  type  based  on  SQLJnt.  Such  an 
object  cannot  be  converted  by  such  a  conversion  to  an  object  of  a  _Type  derived  from 
SQL_Smallint,  SQl_Real,  etc.  The  following  code  fragment  demonstrates  a  conversion  of 
an  object  of  a  null  bearing  type  derived  from  SQLJnt  to  an  object  of  a  null  bearing  type 
derived  from  SQL_Real.  (It  assumes  appropriate  visibility.) 
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If  Is^Null  ( Integer_Object )  then 

Assign  (Real^Gb  ject. ,  Null  SQL_Real) ; 

else 

Assign (Real  Object, 

With__Null (Real  Ob ject^Not_Null (Wifchout_Null ( Integer^ob ject. ) ) ) ) ; 

end  If; 

(Real_Object  is  assumed  to  be  of  type  Real_Object_Type.  Rea!_Object_Not_Null  is  the 
corresponding  non-nuil  bearing  type.) 

Special  care  must  be  taken  when  the  objects  involved  are  of  a  character  or  decimal  domain 
class.  These  domain  class  declarations  contain  subtypes  which  serve  to  introduce  con¬ 
straints,  string  lengths  for  character  domains,  and  scale  for  decimal  domains.  If  the  subtype 
names  are  used  as  the  typemarks  for  the  explicit  type  conversions,  then  the  domains  in¬ 
volved  (that  is,  the  source  and  target  domains  of  the  conversion)  must  specify  the  same 
value  for  these  constraints.  The  procedures  for  these  domain  classes  allow  for  inter-type 
operations.  For  example,  the  character  Assign  will  change  the  length  of  a  string  object,  pad¬ 
ding  with  blanks  or  truncating  silently;  the  decimal  Assign  will  change  scale,  rounding  when 
scale  is  decreased,  providing  zeroes  when  scale  is  increased.  To  access  this  functionality 
and  prevent  runtime  errors,  use  the  type  names  of  the  domain  declaration  rather  than  sub- 
type  names.  (These  have  the  suffix  _Base  rather  than  _Type.  Note:  These  rules  apply  to 
decimal  objects  and  null  bearing  character  string  objects.  Non-null  bearing  character  string 
objects  are  visible,  one  dimensional  Ada  arrays.  The  standard  rules  of  Ada  assignment  ap¬ 
ply  to  them.) 

5.6.2.  Using  Conversion  Functions 

The  support  for  integer  and  decimal  types  in  the  SAME  includes  functions  that  convert  be¬ 
tween  objects  of  those  types  and  objects  of  unrelated  types.  (All  abstract  domains  have 
functions  that  convert  between  the  null  bearing  and  non-null  bearing  types  within  the  domain 
definition.)  There  is  no  such  support  for  the  floating  point  types.  For  the  integer  types,  this 
support  consists  of  the  Image  and  Value  functions.  These  are  semantically  equivalent  to  the 
’Image  and  ’Value  predefined  attributes  for  integer  types,  but  their  character  string  operands 
are  over  the  database  character  set;  that  is,  they  take  or  return  objects  of  type  SQL_Char  or 
SQL_Char_Not_Null  defined  in  SQL_Char_Pkg.  Applications  do  not  have  visibility  to  that 
package  and  cannot  directly  declare  objects  of  those  types.  The  package 
SQL_Base_Types_Pkg,  displayed  in  Figure  3-8,  can  be  used  to  circumvent  this  problem. 

When  taking  the  image  of  a  database  integer  value,  the  resulting  object  can  be  immediately 
converted  to  a  type  visible  and  meaningful  to  the  application.  The  following  is  an  example.  It 
is  coded  within  the  scope  of  use  clauses  for  SQL_Base_Types_Pkg, 
SQL_Base_Types_Pkg.SQL_Char_Ops,  Parts_Definition_Pkg,  and 
Parts_Definition_Pkg.Weight_Ops. 

Int»g«r_Aj*_Charact.«r_Ob  j«ct  :  SQL_Char_Typ«  (SQL_Int_Not__NulI '  Width)  ; 
W«i.ght_Ob}act  :  Waight  Typa; 

begin 

Aaaign ( Int«gar_Aa_Character_Ob jact,  SQL_Chax_Typ« ( Image (Waight_Ob ject) ) ) ; 

end; 

Notice  the  use  of  the  ’Width  attribute  of  the  database  integer  type  to  set  the  length  of  the 
output  type  as  large  as  needed.  Since  Weight_Object  is  of  the  null  bearing  Weight_Type, 
the  Image  function  applied  to  it  returns  an  object  of  the  null  bearing  type 
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SQL_Char_Pkg.SQL_Char.  This  is  immediately  converted  to  the  visible  type 
SQL_Base_Types_Pkg.SQL_Char_Type.  The  proper  overloading  of  the  Assign  procedure, 
in  SQL_Base_Types_Pkg.SQL_Char_Ops,  is  then  found  by  the  compiler,  (The  base  type 
SQL_Char_Type  was  used  for  lnteger_As_Character_Object  under  the  assumption  that  it 
serves  a  general  role  of  preparing  values  for  display,  rather  than  a  role  specific  to  weights.) 

In  order  to  execute  the  Value  function  to  perform  the  inverse  conversion,  the  operand  must 
be  converted  to  the  appropriate  character  base  type.  The  subtype  names  defined  in 
SQL_Base_Types_Pkg  can  be  used  as  typemarks  for  this  conversion.  The  inverse  of  the 
assignment  above  is: 

A**ign  (W«ight_Ob j«ct ,  Valu«  (SQL_Cb*r_Subtyp«  (Int»g«r_A»_Chai.*ct«r  Object)  )  )  ; 

The  decimal  support  package  provides  an  extensive  collection  of  conversion  functions. 
These  convert  between  the  database  integer,  floating  point  and  character  string  types,  both 
null  and  non-null  bearing,  and  the  null  and  non-null  bearing  decimal  types.  Use  of  these 
conversion  functions  follows  the  pattern  described  for  Image  and  Value.  Functions  which 
convert  to  the  other  (non-decimal)  types  are  called  within  the  context  of  a  type  conversion  to 
a  locally  visible,  appropriate  type.  Functions  which  convert  from  those  types  to  a  decimal 
type  take  operands  which  are  of  the  form  of  a  type  conversion  to  the  appropriate  base  type, 
using  the  subtypes  declared  in  SQl_Base_Types_Pkg  as  the  typemark.  For  example,  sup¬ 
pose  lnteger_Object  is  of  a  type  derived  from  SQL_lnt_Not_Null  and  its  value  is  to  be  as¬ 
signed  to  Decimal_Object,  of  a  type  derived  from  SQL_Decimal.  The  following  Assign  pro¬ 
cedure  call  accomplishes  this: 

Assign (Dscimal_Ob j«ct, 

To_SQL_Dscijnal (SQL_Int_Not_Null_Subtyp» (Intsgsx_Objsct) ) ) ; 


5.7.  Using  Three-Valued  Logic 

The  SAME'S  treatment  of  null  values  (see  Section  3.1)  replicates  the  SQL  semantics.  Data¬ 
base  objects  which  might  be  null  can  be  operr.ed  on  with  arithmetic  and  comparison  opera¬ 
tions  in  place.  They  do  not  have  to  be  converted  to  visible  Ada  types.  To  do  this  success¬ 
fully,  however,  the  programmer  must  understand  SQL  semantics  for  the  null  value. 

Briefly,  any  operator  that  is  not  a  conversion  function,  other  than  comparisons,  returns  the 
null  value  when  at  least  one  of  its  inputs  is  the  null  value.  The  comparison  operators  return 
the  truth  value  UNKNOWN  if  one  of  the  comparands  is  the  null  value. 

The  SQL  null  value  represents  missing  or  unknown  information.  The  expressions  "2  +  null” 
means  "add  two  to  a*  unknown  number."  The  answer  is  an  unknown  number,  that  is,  the 
null  value.  Similarly,  the  comparison  "2  >  null”  means  “is  two  greater  than  an  unknown 
number.”  The  answer  is  the  new  truth  value,  UNKNOWN. 

When  using  SQL  arithmetic,  the  programmer  or  analyst  must  decide  whether  the  null  an¬ 
swer  is  acceptable.  The  null  answer  indicates  that  some  of  the  input  was  missing  ana  that 
an  accurate  calculation  is  impossible.  If  the  null  answer  is  not  acceptable,  then  a  strategy  for 
dealing  with  null  values  in  the  input  must  be  chosen.  SQL  will  filter  out  null  values,  but  this 
may  not  be  acceptable  within  the  context  of  the  application,  because  it  may  cause  other 
information  to  be  lost.  Null  values  can  be  detected  with  the  ls_Null  and  Not_Nu!l  Boolean¬ 
valued  functions  that  every  SAME  standard  package  exports.  The  application  must  decide 
what  to  do  with  those  values. 
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SQL  arithmetic  and  three-valued  logic  are  most  useful  in  short  calculations  leading  to  tests. 
For  example,  suppose  a  process  is  to  be  applied  in  case  a  Status  variable  (of  type 
Status_Type,  which  may  be  null)  has  a  value  in  excess  of  one  hundred.  This  can  be  written 
as: 

If  statu*  >  with_Null  (100)  then 
<perform  procaaO 

end  if; 

The  operator  ">"  is  resolved  to  the  Boolean-valued  operator  taking  objects  of  type 
Status_Type  which  operator  is  created  as  part  of  the  derivation  of  Status_Type  from 
SQL_lnt_Pkg,SQL_lnt.  This  operator  returns  "false”  if  either  operand  is  null.  Were  the  proc¬ 
ess  to  be  applied  in  case  Status  might  be  in  excess  of  one  hundred,  it  would  be  written  as: 

If  not  {Statu*  <=  With_Nu.ll  (100) )  then 
<p*r£oim  proc***> 
end  if; 

or  as: 

if  not  Is_Falsa (Status  >  With_Null (100) )  then 
<p«rform  proc*s«> 

end  if; 

In  either  case,  the  process  is  performed  for  a  Status  value  of  null,  as  well  as  known  values 
over  one  hundred. 

Three-valued  logic  can  be  most  heipful  in  evaluating  compound  predicates.  One  can  think  of 
the  versions  of  or  and  and  exported  by  SQL_Boolean_Pkg  as  being  symmetric  versions  of 
Ada's  or  else  and  and  then.  Thus  the  process  in  this  statement 

if  I«_Tru« (Statu*  >  With_Null (100)  or 

Equal* (City,  With_Null ("Pittsburgh") ) )  then 
<p«rfonn  proce**> 
end  If; 

will  be  performed  if  at  least  one  of  the  two  conditions  is  known  to  be  true.  Unlike  Ada’s  or 
else,  the  first  condition  may  be  non-computable,  that  is,  UNKNOWN,  and  the  second  True. 
The  example  can  also  be  written  as: 

if  statu*  >  with_Null  (loo)  or  else 

City  =  With_Null ( "Pittsburgh" )  then 
<p*rform  proc***> 
end  If; 

in  which  case,  the  second  comparison  will  not  be  made  if  the  first  comparison  returns  "true.” 

The  package  SQL_Boolean_Pkg  defines  the  type  Boolean_With_Unknown  and  the  func¬ 
tions  which  operate  on  it.  The  application  program  must  have  visibility  to  that  package  to  use 
those  functions.  As  discussed  above,  the  package  is  meant  to  be  used. 


5.8.  Commenting  Procedure  Calls 

To  improve  the  readability  of  SAME  applications,  it  is  good  practice  to  annotate  the  calls  to 
abstract  interface  procedures  with  an  English  descnption  of  the  call’s  effect.  This  annotation 
should  also  appear  on  the  declaration  of  the  procedure  in  the  abstract  interface.  It  is  bad 
practice  to  use  the  SQL  statement  as  the  annotation.  An  advantage  of  the  SAME  is  that  the 
SQL  statements  in  the  concrete  module  can  be  modified  without  modification,  indeed,  with¬ 
out  recompilation,  of  the  application.  Further,  proper  understanding  of  the  SQL  statement 
requires  an  understanding  of  the  database  structure  and  semantics.  If  the  com  nent  is  in 
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English  and  not  in  SQL,  it  may  be  understood  by  readers  who  are  ignorant  of  the  database 
structure. 


The  SQL  statement  as  comment  may  be  very  uninformative.  The  SQL  fetch  statement 
says  very  little  about  what  is  being  fetched.  In  so  far  as  that  is  present  in  the  concrete  mod¬ 
ule,  it  is  the  associated  declare  cursor  statement.  It  is  better  to  use  an  English  description 
such  as  “retrieves  the  next  pair  of  part  numbers  and  cities  meeting  the  run  time  restriction 
on  supplier  status"  (see  the  example  in  the  introduction)  rather  than  “fetch  x  into 
Part_Number,  City  INDICATOR  City_lndic.” 

It  is  likewise  good  practice  to  comment  the  definition  of  a  row  record  type  with  an  explana¬ 
tion  as  to  the  meaning  of  objects  of  the  type.  This  practice  is  illustrated  in  the  examples  of 
Chapter  8. 
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6.  The  SAME  Method  Summarized 

The  SAME  is  a  modular  approach  to  Ada  SQL  interfacing  that  builds  on  the  capabilities  of 
the  ANSI  standard  module  language.  The  value  added  by  the  SAME  beyond  the  module 
language  itself  includes: 

•  a  safe  treatment  of  null  values 

•  a  robust  treatment  or  exceptional  conditions 

•  full  Ada  typing 

•  decimal  arithmetic  in  Ada 

•  SQL  string  operations  in  Ada 

•  extensibility  to  data  types  not  in  the  SQL  standard  (such  as  Ada  enumeration 
types) 

There  exist  standard  SAME  packages  which  implement  there  features.  They  appear  in  Ap¬ 
pendix  C  of  this  report.  This  support  includes  an  implementation  of  three-valued  logic  which 
conforms  to  SQL  definitions. 

The  SAME  is  used  in  the  following  way: 

•  During  the  database  design  process  the  abstract  domains  occupying  the  data¬ 
base  columns  must  be  identified  and  described  as  Ada  types.  These  type 
definitions  are  stored  as  domain  packages. 

•  During  the  design  of  an  application,  the  services  needed  from  the  database  are 
identified  and  coded  as  SQL  statements.  They  are  collected  into  a  module.  This 
is  called  a  concrete  module. 

•  For  each  data  item  at  the  abstract  interface,  the  type  within  the  abstract  domain 
definition  for  that  item  must  be  determined.  If  the  data  item  is  logically  capable 
of  taking  on  the  null  value,  an  Ada  type  capable  of  taking  on  a  null  value,  e.  g., 
the  _Type  rather  than  the  _Not_Null  type,  must  be  used. 

•  An  abstract  interface  is  created.  This  is  a  set  of  package  specifications  declar¬ 
ing  whatever  record  type  definitions  are  needed  to  describe  row  records  and 
whatever  procedure  declarations  are  needed  to  access  the  relevant  concrete 
module  procedures. 

•  The  abstract  module,  the  bodies  of  the  procedures  declared  in  the  abstract  in¬ 
terface,  is  created.  The  procedures  in  the  abstract  module  ha  the  following 
structure: 

1 .  The  corresponding  concrete  procedure  is  called;  the  global  parameter 
SQLCODE  in  the  package  SQL_Communications_Pkg  is  used  as  the 
<sqlcode  parameter. 

2.  The  SQLCODE  value  is  processed  as  appropriate.  When  unanticipated 
errors  occur,  a  standard  routine,  Process_Database_Error  in  the  pack¬ 
age  SQL_Database_Error_Pkg,  is  called.  This  routine  is  specialized  to  a 
class  of  applications,  e.g.,  batch,  online,  etc.  Upon  return  from  that 
routine,  the  exception  SQL_Database_Error  is  raised. 
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3.  Assuming  the  exception  is  not  raised,  data  values  are  examined  for  null 
(indicator  values)  and  assigned  to  output  parameters  for  type  conver¬ 
sion  and  range  checking.  (If  data  is  flowing  from  the  application  !■'  the 
database,  as  for  update  and  insert  commands,  this  step  occurs  first.  If 
data  is  flowing  in  neither  direction,  as  for  e.g.,  close,  this  step  is 
omitted.) 

•  The  application  program  can  be  written  while  the  abstract  module  is  being  writ¬ 
ten.  It  will  need  access  to  the  relevant  domain  packages  and  to  the  abstract 
interface.  It  can  treat  incomplete  information  (null  values)  in  either  a  "test  and 
convert"  fashion  or  with  the  full  three-valued  logic  and  arithmetic  of  SQL.  It  can 
ignore  all  database  errors  from  which  it  cannot  recover. 

Figure  6-1  diagrams  the  package  structure  of  a  complete  SAME  application.  Although  only 
one  domain  package  and  abstract  interface  module  are  shown,  these  may  be  divided  into 
multiple  packages  at  the  designer's  discretion.  The  shaded  areas  indicate  those  parts  of  an 
application  which  are  unique  to  it.  The  arrows  represent  visibility  (with)  relationships,  not  call 
structure.  The  dashed  arrows  indicate  optional  visibility.  An  application  needs  visibility  to 
SQL_Boolean_Pkg  and  SQL_Exceptions  only  if  it  executes  three-valued  Boolean  operations 
or  provides  an  exception  handler  for  the  Null_Value_Error  exception,  respectively. 

The  packages  within  the  support  layer  are  in  the  SAME  standard  packages  and  are  never 
modified.  The  package  SQl_Database_Error_Pkg  may  be  specialized  for  classes  of  ap¬ 
plications.  The  packages  SQL_System,  SQL_Standard,  and  SQL„Communications_Pkg  are 
specialized  for  the  DBMS  being  used. 
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7.  Building  a  SAME  Application  Without  a  Module 
Compiler 

The  presentation  of  the  SAME  in  these  guidelines  has  assumed  the  existence  of  a  compiler 
for  the  module  language.  The  SAME  can  be  used  in  environments  for  which  no  such  com¬ 
piler  exists.  All  that  is  needed  is  DBMS  support  for  some  programming  language.  With  such 
support,  the  module  language  compiler  can  be  simulated. 

The  simulation  of  the  module  language  compiler  need  not  be  exact,  if  the  DBMS  vendor 
supplies  an  SQL  preprocessor  for  Ada,  it  is  reasonable  to  use  it  and  put  SQL  statements  in 
place  of  tne  calls  to  the  concrete  procedures  in  the  bodies  of  the  procedures  in  the  abstract 
module.  The  division  into  abstract  and  concrete  modules  is  not  an  essential  part  of  the 
SAME.  It  is  used  primarily  for  purposes  of  exposition.  It  is  the  interface  to  the  application,  the 
abstract  interface,  which  is  the  hallmark  of  the  SAME. 

If  the  DBMS  vendor  supplies  no  support  for  Ada,  but  supplies  support  for  other  programming 
languages,  those  foreign  language  processors  can  be  used  in  place  of  the  module  language 
compiler.  This  is  easiest  if  the  DBMS  vendor  allows  database  access  from  a  language  to 
which  the  Ada  compiler  interfaces. 

The  details  of  foreign  language  calls  are  compiler  dependent.  In  general  terms,  a  procedure 
declaration  is  followed  by  a  pragma  INTERFACE  statement  indicating  that  the  procedure  is 
coded  in  a  foreign  language.  This  pragma  may  appear  in  the  body  of  abstract  module  proce¬ 
dures.  When  using  a  foreign  language,  it  is  not  essential  that  the  concrete  module  appear  as 
an  object. 

Example 

The  example  Concrete_Mod  displayed  earlier  is  repeated  here  coded  in  C.  It  is  shown  in 
Figure  7-1  with  its  Ada  call  coded  for  an  Alsys  Ada  compiler  (Release  3.0,  running  on  a 
Sun)  [1],  In  Figure  7-2  it  is  shown  for  a  Verdix  compiler  (Release  5.41,  running  on  a 
VAXStation)  [17].  Both  examples  are  written  for  Ingres  Release  5.0. 29 


^Ingres  5.0  does  not  support  null  values.  Therefore,  the  indicator  parameters  are  missing  from  the  SQL 
statements. 
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Concrete_Mod  in  ‘C’  for  Alsys 

axac  aql  include  aqlca; 

ingcalc  (pnumber,  totalw,  sqlcode) 
axac  aql  begin  declare  section; 
long  pnumber; 
long  ♦totalw; 

axac  sql  and  declare  section ; 
long  *sqlcode; 

{ 

axac  aql  aalact  sum  (qty*waight) 

into  :*totalw 

from  p,  sp 

whara  p.pno  =  ap.pno 

and  p.pno  =  : pnumber; 

♦sqlcode  =  sqlca . sqlcode 

} 

The  Alsys  Ada  declaration 

procedure  Calculate_Waight  (PNUMBER  :  SQL_Standard . Int; 

Total_Weight  :  out  SQL_Standard. Int; 
SQLCODE  :  OUt  SQL_Standard. SQLCODE_Type ) ; 
pragma  INTERFACE  (c,  Calculate_Waight) ; 
pragma  Interface_Nama  (Calculata_Weight,  "ingcalc") ; 

Figure  7-1 :  Concrete_Mod  for  Alsys 
Concrete_Mod  in  ‘C’  for  Verdix 

axac  sql  include  aqlca; 

ingcalc  (pnumber,  totalw,  sqlcode) 
axac  sql  begin  declare  section; 
long  *pnumber; 
long  ♦totalw; 

axac  aql  and  declare  section; 
long  *sqlcode; 

( 

axac  sql  select  sum  (qty*waight) 

into  : *totalw 

from  p,  sp 

whara  p . pno  —  sp . pno 

and  p.pno  =  ; *pnumber; 

♦sqlcode  =  sqlca . sqlcode 

) 

The  Verdix  Ada  Declaration 

procedure  Calc jlate_Waight  (PNUMBER  :  Sy at am. Address ; 

Total_Weight  ;  System. Address; 

SQLCODE  :  System. Address) ; 
pragma  INTERFACE  (c,  Calculata_Weight,  ”_ingcalc" ) ; 


Figure  7-2:  Concrete_Mod  for  Verdix 
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Notice  that  use  of  a  foreign  language  makes  the  abstract  module  compiler  dependent;  if  the 
application  is  moved  to  a  different  compiler,  the  abstract  module  must  be  recoded.  The  ab¬ 
stract  interface  is  not  affected;  therefore,  neither  is  the  application  program. 

As  illustrated  in  Figures  7-1  and  7-2,  the  foreign  language  routines  should  do  only  the  mini¬ 
mum  required.  They  should  contain  almost  nothing  but  SQL  statements  and  data  declara¬ 
tions.  In  particular,  any  differences  between  the  Ada  data  representation  and  the  foreign 
language  representation  should  be  resolved  in  the  Ada  code.  For  examp'e,  C  character 
strings  are  terminated  with  the  ASCII  null.  Ada  strings  are  not.  The  removal  and  addition  of 
the  ASCII  null  can  be  done  in  the  Ada  abstract  module. 

One  must  be  careful  in  using  foreign  language  routines  in  an  Ada  program.  There  is  no  type 
checking  across  the  boundary  between  Ada  and  the  foreign  language.  Be  sure  to  verify  the 
types  by  hand.  Be  sure  to  leave  enough  room  in  character  strings  to  accommodate  the  AS¬ 
CII  null  at  the  end  of  C  strings,  for  example. 

If  the  set  of  languages  which  the  compiler  recognizes  is  disjoint  from  the  set  of  languages 
which  the  DBMS  supports,  it  will  be  necessary  to  write  an  extra  interface  procedure.  This 
has  not  been  attempted  as  of  this  writing;  thus,  little  guidance  can  be  offered. 
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8.  Some  Detailed  Examples 

This  section  presents  an  example  of  the  use  of  the  SAME,  illustrating  features  of  a  SAME 
application  and  a  SAME  abstract  module.  Details  of  the  application  which  are  irrelevant  to 
the  database  interaction  are  not  shown;  in  particular,  the  details  of  user  interaction  are  sup¬ 
pressed.  Only  those  fragments  of  the  application  which  acquire  and  manipulate  database 
data  will  be  presented 

The  design  decisions  in  the  examples  are  contrived  to  illustrate  the  coding  aspects  of  ab¬ 
stract  modules  and  application  programs.  The  example  should  not  be  taken  as  an  example 
of  good  program  design. 

The  example  accesses  the  Parts-Supplier  database  described  in  Figure  1-6.  The  abstract 
domains  describing  that  database  are  to  be  found  in  Figures  3-6  and  3-7.  The  overall  struc¬ 
ture  of  the  application  is  shown  in  Figure  8-1.  The  driver  block  is  responsible  for  user  com¬ 
munication.  Based  on  user  input,  the  driver  block  determines  which  application  service  has 
been  requested  and  calls  the  appropriate  subprogram,  the  blocks  labeled  example_a 
through  example_c  in  Figure  8-1 .  The  driver  program  will  not  be  shown.  Each  of  the  ex¬ 
ample  blocks  has  an  associated  display  facility  which  is  responsible  for  displaying  the 
module’s  results  on  the  user  terminals.  These  display  facilities  will  also  not  be  shown.  The 
complete  text  of  the  example  subprograms  and  of  the  abstract  modules  will  be  presented. 
(This  architecture  was  chosen  so  that  complete  subprograms  could  be  shown  and  irrelevant 
details  could  be  suppressed.) 

Notice  that  there  is  only  concrete  module  in  Figure  8-1 ,  labeled 
EXAmple_0Oncrete_module.  There  are  three  abstract  modules,  one  for  each  of  the  distinct 
parts  of  the  application.  They  contain  just  those  database  procedures  and  definitions  which 
are  relevant  to  the  application  services  they  support.  The  bodies  of  the  abstract  modules 
depend  on  (with)  the  concrete  module.  Modifications  to  and  recompilation  of  the  concrete 
module  will,  in  general,  require  recompilation  of  the  bodies  of  the  abstract  modules,  but  not 
their  specifications  and,  therefore,  not  those  parts  of  the  application  which  are  unaffected  by 
the  changes  to  the  concrete  module. 

Example_A 

In  Example_A,  the  user  enters  the  number  of  a  part  and  requests  the  number  of  outstanding 
orders  for  that  part  and  the  total  weight  of  those  shipments.  The  SQL  module  procedure 
which  retrieves  this  information  is  given  in  Figure  8-2.30  The  corresponding  abstract  module 
specification  is  given  in  Figure  8-3. 

The  single  procedure  PartWeight  in  the  Ada  abstract  module  Example_A_Module  takes  a 
part  number  as  its  single  input  parameter  and  returns  a  record  containing  the  part  number, 
the  requested  weight  and  count,  and  a  Boolean  result  parameter.  (The  part  number  is  added 
to  the  output  row  record  type  so  that  objects  of  that  type  have  a  well  defined  meaning.  The 
comments  on  the  row  record  definition  in  Figure  8-3  give  that  meaning.  It  is  good  practice  to 
comment  row  record  type  definitions  in  this  way.)  The  Boolean  takes  the  value  false  when 
the  requested  part  number  does  not  have  any  shipments  in  the  database,  in  which  case  the 


30Figures  containing  SQL  or  Ada  code  appear  at  the  end  of  each  example. 
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Figure  8-1 :  A  Block  Diagram  of  the  Example 

value  of  the  record  object  is  unreliable.  Although  the  SQL  statement  references  the  quantity 
(Qty)  column  of  the  SP  table,  the  abstract  module  does  not  need  visibility  to  the  QTY 
domain  defined  in  QTY_Definition_Pkg  (see  Figure  3-6)  since  no  values  of  the  QTY  domain 
are  passed  across  the  abstract  interface. 

The  Weight  component  of  the  result  record  takes  a  null  bearing  type,  Weight_Type,  as  the 
value  returned  from  the  SQL  statement  may  be  null.  (It  will  be  null  when  the  Weight  column 
of  the  P  table  entry  for  the  given  Pno  is  null.)  Notice  that  the  SQL  staterm  ,  bar  an  indicator 
variable  attached  to  the  output  target  specification  for  Weight_Out.  signalii  '  -t  a  null 
result  is  possible.  The  Count  component  of  the  result  record  takes  a  non-null  oearing  type 
as  the  corresponding  value  of  the  SQL  statement  cannot  be  null  and  therefore  does  not 
have  an  attached  indicator  variable. 

The  type  of  the  Count  component,  SQL_lnt_Not_Null,  is  one  of  the  "base  domains"  defined 
in  the  package  SQL_Base_Types_Pkg.  The  package  is  described  in  Chapter  3.8. 

The  bulk  of  Example_A  reformats  the  database  input  for  the  purpose  of  display.  The  details 
of  the  communication  with  the  display  device,  including  screen  formats,  are  hidden  in  the 
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separately  compiled  subprogram  Display_The_Line_A.  Among  other  things,  Example_A 
must  convert  integers  into  character  strings.  It  uses  the  SAME  function  Image,  not  the  Ada 
predefined  attribute  function  'Image,  as  the  former  returns  its  value  in  the  underlying  ma¬ 
chine  character  set  whereas  the  latter  returns  its  value  in  ASCII.  In  this  and  the  other  ex¬ 
amples,  each  item  to  be  displayed  has  an  associated  length  field.  (The  component  Pno  of 
the  Display JJne  type  does  not  have  a  length  field,  as  this  component  is  fixed  length.  The 
other  fields  have  an  associated  length,  as  the  length  of  an  integers’s  image  depends  on  its 
value.)  Because  the  Count  component  within  the  Weight_Count_Record  has  a  _Not_Null 
type,  the  Image  function  applied  to  it  returns  a  character  string  of  the  unconstrained  array 
type  SQL_Char_Pkg.SQL_Char_Not_Null.  The  length  of  that  string  is  returned  by  the 
’Length  predefined  Ada  attribute.  The  Weight  component  has  a  null  bearing  _Type,  so  the 
Image  function  applied  to  it  returns  an  object  of  the  limited,  discriminated  type 
CQL_Char_Pkg.SQL_Char.  The  length  of  that  object  is  the  value  of  the  discriminant, 

Length.  The  character  strings  themselves  must  be  converted  to  the  type 
SQL_Base_Types_Pkg.SQL_Char_Not_Null.  These  conversions  should  consume  no  run¬ 
time  resources.  (This  usage  of  the  SQL_Char  domain  in  SQL_Base_Types_Pkg  is  illustra¬ 
tive  of  interfaces  to  low-level  services.  Section  3.8  discusses  these  seivices  and  various 
strategies  for  using  them.) 

The  body  of  Example_A’s  abstract  module  is  presented  in  Figure  8-6.  Its  structure  is  typical 
of  abstract  procedures  whose  SQL  statement  is  a  <select  statement  (SELECT  ...  INTO). 
Since  concrete  procedures  use  the  types  in  SQL_Standard  as  parameter  types,  the  input 
and  output  part  numbers  must  be  converted,  using  an  Ada-explicit  type  conversion,  to 
SQL_Standard.Char.  (Notice  that  the  output  part  number  is  deposited  directly  into  the 
application’s  buffer  from  the  concrete  module’s  output.  Every  component  of  a  row  record 
object  must  be  set  from  a  parameter  of  the  concrete  module,  even  in  a  case  like  this  one,  in 
which  an  output  value  is  by  definition  identical  to  an  input  value.)  This  conversion  consumes 
no  runtime  resources.  After  the  concrete  procedure  is  called,  the  SQLCODE  value  is 
analyzed  according  to  the  needs  of  the  application.  Condition  codes  other  than  Not_Found 
or  successful  completion  (zero)  invoke  standard  error  processing. 

If  the  input  part  number  exists  in  the  database,  the  data  returned  must  be  converted  to  the 
abstract  application  types.  Since  the  Count  component  of  the  output  is  a  _Not_Null  type, 
that  is,  a  visible  Ada  integer  type,  the  value  returned  from  the  concrete  module  can  be 
deposited  directly  in  the  output  component.  Thus,  with  respect  to  the  Count  component,  the 
abstract  module  introduces  no  runtime  overhead. 

Since  the  Weight  component  may  be  null,  the  abstract  module  must  examine  the  indicator 
variable  for  weight  to  determine  if  the  actual  value  is  null.  The  package  Conversions  was 
written  to  facilitate  this.  Its  specification  and  body  are  presented  in  Figure  8-7.  The  use  of 
the  Convert  functions  declared  in  package  Conversions  simplifies  the  writing  of  abstract 
module  bodies.  Those  functions  return  objects  of  the  base  null  bearing  types,  SQLJnt, 
SQL_Char,  etc.  Abstract  modules  do  not  have  visibility  to  the  packages  in  which  those 
types  are  declared,  for  reasons  discussed  in  Section  3.8.  Thus  the  values  returned  by  these 
functions  must  be  immediately  converted  to  the  output  abstract  type,  as  shown.  (Notice  the 
use  of  pragma  Inline  in  package  Conversions  to  eliminate  the  expense  of  a  procedure  call.) 
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PROCEDURE  PartWaight 
Pno_In  Char  (I) 

Pno_Out  Char  (5) 

Waight  Out  Int  Waight_Indic  Smallint 

Count_Out  lit 

SQLCODE; 

SELECT  DISTINCT  P.Pno,  Waight  *  Sum(Qty),  Count ( SP . SNO ) 

INTO  P  no_Out 

Waight_Out  INDICATOR  Waight_Indic , 

Count_Out 
FROM  P ,  SP 

WHERE  P.Pno  =  SP.Pno  and  P.Pno  =  Pno_In; 

Figure  8*2:  The  SQL  Procedure  for  Example_A 

With  SQL_Base_Types_Plcg,  Parts_Daf inition_Pkg; 
use  SQL_Base_Types_P)cg,  Parts_Daf inition_Pkg; 
package  Exampla_A_Module  is 

type  Waight_Count_Racord_Typ«  is  record 

Pno  :  Pno_Not_Null ;  --  all  tha  shipments  for  this  part 

Haight  :  Waight_Typa;  --  hava  thi«  combinad  weight. 

Count  SQL_Int_Not_Null;  --  there  ara  thaaa  many 

end  record  ; 

procedure  PartWaight  (Pno  in  Pno_Not_Null ; 

Waight_Count  in  out  Waight  Count  Racord_Typa; 
Exist#  :  OUt  boolaan) ; 

--  tha  result  waight  is  tha  combinad  gross  waight 
—  of  all  shipmants  of  tha  input  Waight 
--  Exists  is  Falsa  whan  Pno  not  in  database 

end  Example__A_Module  ; 

Figure  8-3:  The  Abstract  Module  for  Example_A 
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with  Parts_Def inition_Pkg,  SQL_Baae_Types_Pkg,  Example_A_Module ; 
use  Parts_Def inition_Pkg,  SQL_Base_Typee_P!-g ,  Exan^jle_A_Module; 
separate  (Driver) 

procedure  Exaraple_A  (Pno  Pno_Not_Null)  is 

use  SQL  Char  Ops,  SQL  Int  Ops;  —  Base  hype  subpackages 

use  Character_Set;  —  For  literal  formation 

--  literals  for  display 

No_Data  :  constant  SQL_Char_Not_Null  := 

"Part  Number  Not  in  Database"; 

Nul  ^Weight  :  constant  SQL_Char_Not_Null  := 

"Null  Weight" ; 

—  types  used  for  display 

type  Message_Type  is  (Error  Msg,  Data_Msg)  ; 

type  Display_Line  (Message  :  Message _ Type )  is  record 

Pno  :  SQL_Char_Not_Null (Pno  Not_Null ' Range) ; 
case  Message  is 

when  Data_Msg  => 

Weight  Length,  Count  Length  :  Integer; 

—  these  are  lengths  of  the  data  in  the 

—  next  two  fields,  which  are  declared  to  be 

—  of  a  maximum  length,  which  in  most  cases  is 

—  much  too  large 

Weight  :  SQL_Char_Not_Null (1  .. 

Weight_Not_Null' Width) ; 

Count  :  SQL_Char_Not_Null (1  . . 

A_Database_Integer_Not  Null 'Width) ; 

when  Error_Msg  => 

—  when  the  part  number  doesn't  exist,  this 
--  variant  is  used 

Mssg  ;  SQL_Char_Not_Null (No_Data' Range)  :=  No_Data; 
end  case; 
end  record; 

—  objects  used  for  display 

Data_Line  :  Display_Line (Message  =>  Data_Msg) ; 

Error_Line  :  Display _Line (Message  =>  Error  Msg) ; 

—  objects  used  for  communication  with  Abstract  Module 
Tuple  :  Weight_Count_Record_Type;  —  holds  the  output 
ls_Found  ;  Boolean; 

—  the  display  procedure,  which  will  not  be  shown 
procedure  Display_The_Line_A  (Line_To_Display  :  Display_Line) 

is  separate  ; 

Figure  8-4:  Example_A  (Part  I) 
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begin 

PartWeight  (Pno,  Tuple,  Is_Found)  ;  --  The  Abstract  procedure 

if  Is_Found  then  —  Part  Nbr  good;  prepare  output 

Data  Line, Pno  :=  SQL  Char  Not_Null (Tuple . Pno) ; 

Data_Line . Count_Length  :=  Image (Tuple . Count )' Length ; 

Data_Line . Count (Data  Line  .  Cotint '  Firat  .. 

Data_line . Count ' First  +  Data_Line . Count  Length  -  1) 

SQL_Char_Not_Null (Image (Tuple .Count) ) ; 
if  Not_Null (Tuple .Weight)  then  —  for  non  null  weights 

—  prepare  outputs 

Data_Line.Weight_Length  ;=  Image (Tuple .Weight) -Length; 
Data_Line . Weight (Data_Line . Weight ' First 

Data_Line . Weight ' First  +  Data_Line . Weight_Length  -  1) 

;  e 

Without_Null (SQL_Char  Type (Image (Tuple .Weight) ) ) ; 
else  —  for  null  weights,  prepare  a  message 

Data_Line . Weight_Length  : =  Null_Weight ' Length; 

Data_Line -Weight  :=  Null_Weight; 
end  If; 

Display_The_Line_A (Data_Line) ;  —  put  out  a  line  of  data 

else  --  the  Part  Nbr  not  in  DB 

Error_Line .Pno  :=  SQL_Char_Not_Null (Pno) ; 

Display_The_Line_A  (Error_Line) ;  --  a  message  about  missing  Part 

end  If; 

end  Example_A; 

Figure  8-5:  Example_A  (Part  II) 
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With  Conversions.  SQL  Standard,  SQL  Comnunications  Pkg, 
SQL_Database_Error_Pkg ; 

use  Conversions,  SQL  Standard.  SQL  Communications  Pkg, 

SQL_Dat  base__Error_Pkg ; 

With  Example_Concrete  Module; 
package  body  Examp l e_A_Mo du l e  is 

package  Cone  renames  £xample_Concrete_Module; 

Use  Weight_Ops; 

procedure  PartWeight  (Pno  in  Pno_Not_Null; 

Weight  Count  :  In  OUt  Weight_Count_Record  Type; 
Exists  ;  OUt  boolean)  is 

Weight_Temp  Int; 

Weight_Indic  Indicator_Type ; 

begin 

Cone -PartWeight (Char (Pno) , 

Char (Weight_Count . Pno) , 

Weight  Temp,  Weight  Indie, 

Int (Weight_Count . Count) , 

SQLCODE) ; 

if  SQLCODE  in  Not  Found  then  —  no  such  part  no 
Exists  : ■  false: 

elsif  SQLCODE  /=  0  then  --  unrecoverable  error 
Process_Database_Error ; 
raise  SQL_Database_Error ; 

else 

Exists  :  =  tirue;  —  record  retrieved  as  expected 

Assign (Weight_Count . weight , 

Weight_Type (Convert (Weight__Temp,  Weight_Indic) ) ) ; 

end  If;  - 

end  PartWeight; 
end  Example_A  Module; 

Figure  8-6:  The  Abstract  Module  Body  for  Example_A 
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with  SQL_Standai -  SQL_Int_Pkg,  SQL_Smallint_Pkg, 

SQL_Char_Pkg,  SQL_Real_Pkg . 

SQL  Double  Precision_Pkg; 
use  SQL_Standard,  SQL_Int_Pkg,  SQL_Smallint_Pkg, 

SQL_Char_Pkg,  SQL_Re*l_Pkg , 

SQL  Double  Precision_Pkg; 

package  Conversion#  is 

function  Convert  (Input  :  Int;  Indicator  Indicator_Type) 
return  SQL_int; 

function  Convert  (Input  :  Smailint;  Indicator  :  Indicator_Type) 
return  SQL_Smallint; 

function  Convert  (Input  :  Char;  Indicator  Indicator  Type) 
return  SQL_Char; 

function  Convert  (Input  :  Real;  Indicator  Indicator  Type) 
return  SQL_Real; 

function  Convert  (Input  Double  Precision;  Indicator  Indicator_Type) 
return  SQL_Double_Precision; 
pragma  inline  (Convert)  ; 
end  Conversions; 

package  body  Conversions  is 

subtype  Null_Indication  is  Indicator  Type  --  Negative  value 
signals  Null 

range  Indicator_Type'  First  ..  -1; 

function  Convert  (Input  ;  Int;  Indicator  :  Indicator_Type) 
return  SQL_lnt  is 

begin 

If  Indicator  in  Null_Indication  then 
return  Null_SQL_Int; 

else 

return  With_Null_Base (SQL_Int_Not_Null (Input) ) ; 
end  If; 

end  Convert; 

function  Convert  (Input  :  Smailint;  Indicator  :  Indicator_Type) 
return  SQL_Smallint  is 

begin 

if  Indicator  in  Null_Indication  then 
return  Null_SQL_Smallint; 

else 

return  With_Null_Baae  (SQL  Smallint_Not_Null  (Input)  )  ; 
end  if; 

end  Convert; 

function  Convert  (Input  Real;  Indicator  Indicator  Type) 
return  SQL_Real  is 

begin 

if  Indicator  in  Null_Indication  then 
return  Null_SQL_Real; 

else 

return  With_Null_Base  (SQL__Real_Not_Null  (Input)  )  ; 
end  if; 

end  Convert ; 

function  Convert  (Input  Double_Preci#ion ;  Indicator  Indicator_Type) 
return  SQL_Double_Precision  IS 

begin 

if  Indicator  in  Null  Indication  then 
return  Null  SQL_Double_Precision; 

else 
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return  With_Null_Baae  (SQL_Double_Preciaion_Not_Null  (Input)  )  ; 
end  if; 

end  Convert.  ; 

function  Convert  (Input  Char;  Indicator  Indicator  Type) 
return  SQL_Char  is 

begin 

If  Indicator  in  Null_Indication  then 
return  Null_SQL_Char  ; 

else 

return  With_Null_Baae  (SQL_Char_Not_Null  (Input)  )  ; 
end  If; 

end  Convert ; 
end  Converaiona; 

Figure  8-7:  The  Conversions  Package 
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Exampie_B 

Example_B  accepts  a  part  number  from  the  user  and  returns  information  about  each  ship¬ 
ment  of  the  part:  the  part  number,  the  name  of  the  supplier,  and  the  total  weight  of  the 
shipment.  As  there  are,  in  general,  jltiple  shipments  for  a  part,  a  cursor-oriented  retrieval 
is  needed.  The  SQL  text  of  the  cursor  declaration  and  its  associated  procedures  is  given  in 
Figure  8-8  and  the  abstract  module  specification  in  Figure  3-9.  In  the  abstract  module,  the 
cursor  procedures  appear  in  a  subpackage  whose  name  is  the  cursor  name,  Detail.  This 
usage  is  inessential,  in  this  case,  as  the  abstract  module  contains  only  these  procedures. 

For  applications  which  manipulate  multiple  cursors,  the  use  of  abstract  module  subpackages 
in  this  way  will  improve  the  readability  of  the  code  and  prevent  name  conflicts. 

Example_B,  which  is  displayed  in  Figure  8-10,  declares  a  display-oriented  record  type  con¬ 
taining  a  variant  for  part  numbers  which  have  no  shipments.  The  body  of  Example_B  opens 
the  cursor,  passing  the  part  number  into  the  open  procedure,  and  then  retrieves  each  row  of 
the  result,  formatting  and  displaying  each  of  them.  Notice  that  the  initial  fetch  is  done  outside 
of  the  loop,  as  an  end  of  file  condition,  for  this  fetch  means  the  part  was  not  found.  There¬ 
fore,  the  loop  body  first  displays  the  current  tuple  and  then  fetches  the  next  tuple.  This  is  a 
typical  paradigm  for  cursor-oriented  database  retrieval 

The  body  of  the  while  loop  illustrates  two  new  features.  The  SNAME  character  string  value 
has  its  trailing  blanks  removed  by  the  Without_Null_Unpadded  function  generated  by  the 
instantiation  of  the  SNAME_Ops  subpackage.  (Hence,  the  use  for  that  subpackage.)  The 
length  of  that  function  result  is  returned  by  the  Unpadded_Length  function. 

The  loop  body  also  contains  an  example  of  mixed  mode  arithmetic.  Recall  that  Example_B 
returns  to  the  user  the  total  weight  of  each  shipment,  the  product  of  the  weight  of  a  part,  and 
the  quantity  of  items  shipped.  This  value  could  have  been  produced  by  the  SQL  statement, 
which  would  in  reality  have  been  preferable.  It  was  not  done  in  order  to  illustrate  mixed 
mode  arithmetic  operations  in  the  SAME. 

The  quantity  vaiue  is  converted  to  the  weight  type,  as  the  target  value  has  weight  type.  Be¬ 
cause  the  null  bearing  _Type(s)  are  in  use,  this  Ada  explicit  type  conversion  will  not  produce 
any  runtime  exceptions.  If  the  _Not_Null  types  were  in  use  and  were  range  constrained, 
care  would  be  needed  to  ensure  that  a  runtime  constraint_error  is  not  raised. 

The  body  of  Example_B_Module,  the  abstract  module  for  Example_B,  appears  in  Figure 
8-1 1 .  Neither  the  Open  nor  the  Close  procedures  will  accept  any  SQLCODE  values  other 
than  success,  e.g.,  the  value  zero.  These  procedures  take  no  result  parameter,  therefore. 
The  fetch  procedure  signals  end  of  file  by  returning  the  false  Boolean  value  in  its  .esult 
parameter. 

When  a  tuple  is  returned,  its  values  must  be  converted  to  the  applicai  on’s  abstract  types. 
Again  the  Pno  value,  which  cannot  be  null,  is  deposited  directly  into  the  application  s  buffer. 
The  values  of  those  items  which  may  be  null  are  read  into  intermediate  variables  in  the 
abstract  module’s  data  space.  They  are  tested  for  null  and  converted  to  the  application  s 
types  using  the  assign  and  convert  functions  shown  in  Example_A's  abstract  module. 

Notice  the  use  statement  for  the  generic  subpackage  instantiations  of  the  integer  domains, 
Weight,  and  QTY.  This  use  statement  makes  the  assign  procedures  for  these  domains 
visible. 
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Again,  the  values  returned  by  the  Convert  functions  have  the  SAME  base  types  (SQL  Int, 
SQL_Char,  etc.)  and  must  therefore  immediately  be  converted  to  the  application's  types. 
This  is  done  with  an  Ada-explicit  type  conversion.  For  the  character  string  based  SNAME 
domain,  the  target  of  the  type  conversion  is  SNAME_Base  and  not  the  SNAME_Type  sub- 
type.  Recall  that  the  definition  of  a  character  string  domain  consists  of  two  type  declarations, 
two  subtype  declarations,  and  a  package  instantiation.  The  type  declarations  declare  uncon¬ 
strained  types;  the  subtypes  specify  the  constraint,  i.  e.,  the  string  length.  Now  if  a  given 
value  is  null,  the  Convert  function  will  return  Null_SQL_Char,  an  object  cf  type  SQL_Char. 
This  object  must,  of  course,  have  a  discriminant  constraint  (a  Length).  Since  Convert  works 
only  with  base  types,  it  cannot  know  how  "long”  to  make  this  null  value.  Thus  the  length  of 
Null_SQL_Char  is  one.  If  this  object  were  converted  to  the  subtype  SNAME_Type,  a 
constraint_error  (discriminant_error)  would  occur.  Since  the  type  SNAME_Base  is  uncon¬ 
strained,  the  type  conversion  to  it  avoids  the  runtime  exception. 

DECLARE  Detail  CURSOR  FOR 

SELECT  P.Pno,  S. Sname,  SP.Qty,  P .Weight 
FROM  S,  P,  SP 

WHERE  S.Sno=SP.Sno  AND  P.Pno  =  SP.Pno  and 
P.Pno  =  Pno_In; 

PROCEDURE  DetailOpen 
Pno_In  Int 
SQLCODE ; 

OPEN  Detail; 

PROCEDURE  FetchDetail 
Pno  Char  (5) 

Sname  Char  (20)  Sname_Indic  Smallint 
Qty  Int  Qty_Indic  Smallint 
Weight  Int  Weight_Indic  Smallint 
SQLCODE ; 

FETCH  Detail 

INTO  Pno, 

Sname  INDICATOR  Sname_Indic, 

Qty  INDICATOR  Qty_Indic, 

Weight  INDICATOR  Weight  Indie; 


PROCEDURE  CloeeDetail 
SQLCODE ; 

CLOSE  Detail; 

Figure  8-8:  The  Cursor  Declaration  and  SQL  Procedures  for  Example_B 
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With  QTY_Def initio n_P kg,  Supplrers_De£mi.ti.on_Pkg,  Parta_D*finitior>  Pkg; 
use  QTY_Def inition_Pkg,  Suppliers  Definition_Pkg,  P*rts_Def initron  Pkg; 
package  Ex*mpl*_B_Modul*  is 

type  D*tail_R*cord_Type  is  record 
Pno  :  Pno_Not_Null ; 

SHame  :  SNAME_Type; 

Oty  :  QTY_Type; 

Haight  :  Haight  Type; 

end  record  ; 
package  Detail  is 

procedure  Oper.  (fno  ;  in  Pno_Not_Hull)  ; 

—  Create*  a  file  of  Detail  Record*  for  the  part 

—  whose  number  is  given 

procedure  Fetch  (Tuple  :  in  out  Detail_Record_Type ; 

Found  :  out  Boolean) ; 

—  returns  the  records  created  by  the  open 

—  found  becomes  false  at  eof 

procedure  close; 
end  Detail; 

end  Example_B_Module; 

Figure  8-9:  The  Abstract  Module  for  Example_B 


—  this  part  shipped  by 
--  this  supplier 

—  in  this  quantity 

—  each  part  weighs  this  much 
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with  Example_B_Module,  Parts_Def  inition_Pkg,  Suppl iers_Def inition_Pkg, 
QTY_Def inition_Pkg,  SQL_Base_Typea_Pkg; 
use  Example_B_Module,  Parts_Def inition_Pkg,  Suppliera_Def  mition_Pkg, 
QTY_De  f i ni t i  on_P  kg ,  SQL_B  a  a  e_Type  a__P  k  g ; 
separate  (Driver) 

procedure  Example_B  (Pno  :  Pno_Not_Null)  Is 

Use  Character_Set ,  SNAME_Opa,  Weight  Opa,  SQL_Char_Cps ; 


—  literal  for  error  meaaage  diaplay 

No_Data  :  constant  SQL_Char_Not_Null  :="Part  Number  "  i 

SQL_Char_Not_Null (Pno)  £  "  haa  no  ahipmenta"; 

—  Strlnga  For  Printing  Null  valuea 

Null_Sname  :  constant  SQL_Char_Not_Null  :=  "No  Supplier  Name"; 
Null_Weight  :  constant  SQL_Char_Not_Null  :=  "No  Weight"; 

—  type*  for  diaplay 

type  Line_Type  Is  (Error_Line,  Data  Line)  ; 
type  Diaplay_Line  (Kind  :  Line_Type)  Is  record 
case  Kind  is 

When  Error  Line  => 

--  thia  ia  uaed  whan  the  part  haa  no  ahipmenta 

Maag  :  SQL_Char__Not  Null  (No__Data' Range)  :=  No  Data; 
When  Data_Line  =>  ~ 

—  thia  ia  uaed  when  the  part  can  be  found 

—  each  field  (except  Pno) 

—  haa  a  length  field.  The  field  ia  big  enough 

—  for  the  largeat  poaaible  value.  The  length  field 

—  containa  the  aize  of  the  actual  value. 


Pno  :  SQL_Char_Not_Null ( Pno_Not_Null ' Range ) ; 
Sname_Length  :  integer ; 

Sname  :  SQL_Char_Not_Null ( Sname_Not_Null ' Range ) ; 
Total_Weight_Length  :  integer; 

Total_Weight  :  SQL_Char_Not_Null (1  .. 


end  case; 


Weight_Not_Null' Width)  ; 


end  record; 


—  Put  the  display  line  out  (not  shown) 
procedure  Display__The_Line_B  (A_Line  :  in  Diaplay_Line) 
is  separate  ; 


—  body  of  Example  B 

begin 

declare 

Tuple  :  Detail_Record_Type ; 

Found  :  Boolean;  —  true  signals  EOF 

Error_Meaeage  :  Display_Line (Error_Line) ;  —  displayed  no  ship 
Data_Message  :  Display_Line (Data_Line) ;  —  if  shipments 
Total_Weight_Temp  :  Weight_Type; 
begin 

Detail .Open (Pno) ; 

Detail .Fetch (Tuple,  Found);  --  get  first  line  of  result 

If  not  Found  then  —  no  such  part 

Display_The_Line_B  (Ei.ror_Mesaage)  ; 

end  if; 

While  Found  loop 

Data_Measage .Pno  :=  SQL_Char_Not_Null (Tuple .Pno) ; 

If  Ia_Null  (Tuple  .  Sname )  then 

Data_Meaaage . Sname (Null_Sname ' Range)  : =  Null  Sname ; 
Data_Meaaage . Sname_Length  :=  Null  Sname' Length; 

else 

Data_Meaaage . Sname_Length  : =  Dnpadded_Length (Tuple . Sname )  ; 
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Data_Message . SnajM  (Dat»_Mesaage . Sname ' First 

Data_Messi.ge  .  Snama  First  +  Data  Message . Snams  Length  -  1) 

SQL_Char_Not_Null (Without  Hull  Onpadded (Tupla . Snana) ) ; 

end  if; 

—  An  ax amp la  of  mixed  mod*  arithmitic 
assign (Total_Weight_Teinp , 

Tupla. Waight  *  Weight_Type (Tupla . ©ty) ) ; 

If  Is_Null (Total_Weight_Temp)  then 

Data_Msssage.Total_Weight (Null_Weight' Range)  :*  Null_Weight; 
Data_Meaaage.Total_Weight_Langth  :■  Null_Waight ' Length; 
else 

Data_Massaga  .  Total_Waight  Length  :  «= 

Image  (Total_Weight__Tamp) .Length; 

D«ta_Meesage . Total_Weight (Data_Mes#age . Total_Weight ' First  . . 
Data_Message . Total_Waight ' First  + 

Data_Messaga . Total_Waight_Length  -1) 

W i thout_N u 1 1 (SQL_Char  Type (Image (Total  Weight  T amp) ) ) ; 

end  If; 

Display _ The _ Lina^B (Data_Ma*sage) ;  —  display  this  line 

Detail. Fateh (Tupla,  Found);  —  get  next  line 

end  loop; 

Detail .Close; 

end; 

end  Exampl*_B; 

Figure  8-10:  Example_B 
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with  Conversion*,  SQL_Standard,  SQL_Communications_Pkg, 
SQL_Databa*e_Error_Pkg,  Example_Concret«_Modul«; 
use  Conversions,  SQL_Standard,  SQL_C<Mr;r",*nic«iii  ^..s_Pkg, 

SQL  Databaae_Error_Pkg; 
package  body  Exaiaple_B_Module  is 

package  Cone  renames  Exanipl*_Concret*_Modul*; 

use  Weight_Ops ,  QTY_Ops ; 

package  body  Detail  is 

procedure  Open  (Pno  :  in  Pno_Not_Null )  Is 

begin 

Cone .DetailOpen (Char (Pno) ,  SQLCODE) ; 

if  sqlcode  /=o  then 

Proc*ss_Database_Error ; 
raise  SQL_Databa*e_Error; 
end  If; 
end  Open; 

procedure  Fetch  (Tuple  :  in  out  Detail_Racord_Type; 

Found  :  Out  Boolean)  is 

Sname  :  Char  (Snama  Not_Null ' Range) ; 

Height,  Qty  :  Int; 

Sn*me_Indic,  Weight_Indic,  Qty_Indic  ;  Indicator_Type; 
begin 

Cone. FetchDetail (Char  (Tuple. Pno) , 

Sname,  Sname_Indic, 

Qty,  Qty_Indic, 

Weight,  Weight_Indic, 

SQLCODE); 

If  SQLCODE  in  Not_Found  then  —  end  of  file 

Found  :«=  False; 

elslf  SQLCODE  in  SQL_Error  then  —  unrecoverable  error 
Process  Datab*se_Error ; 
raise  SQL  Database_Error; 

else  —  a  tuple  is  returned 

assign (tuple . Snama , 

SNAME_Base (Convert (Snama ,  Sname _ Indi c ) ) )  ; 

assign (tuple .Qty, 

QTY  Type (Convert (Qty,  Qty_Indic) ) ) ; 
assign (tuple .Weight , 

W*ight_Typ* (Convert (Weight,  Weight_Indic)  )  )  ; 
Found  :=  true; 
end  if,- 
end  Fetch; 
procedure  Close  is 
begin 

Conc.Clo**Detail (SQLCODE) ; 

If  SQLCODE  in  SQL_Error  then 
Process  Databas*_Error; 
raise  SQL_Database_Error; 
end  If; 
end  Close; 
end  Detail; 
end  Example_B_Module; 

Figure  8-1 1 :  The  Abstract  Module  Body  for  Example_B 
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Example_C 

Example_C  illustrates  a  database  update.  The  user  enters  a  supplier  number  and  a  signed 
i.'.teger.  If  a  supplier  wiih  that  number  exists  in  the  database,  and  if  that  supplier’s  status  is 
not  null,  the  integer  is  added  to  the  supplier’s  status.  If  the  supplier’s  status  is  null,  it  is  re¬ 
placed  by  the  value  of  the  integer.  In  other  words,  for  this  update,  the  null  value  is  treated  as 
though  it  were  zero. 

The  SQL  statements  for  Example_C  appear  in  Figure  8-12  and  the  abstract  module  specifi¬ 
cation  in  Figure  8-13.  In  the  current  SQL  standard,  two  SQL  update  statements  are  needed. 
One  statement  is  used  for  the  case  that  the  original  status  is  null;  the  other  statement  is 
used  in  the  remaining  case.  (In  the  SQL2  standard,  this  update  can  be  performed  by  a 
single  statement.)  Hence,  it  becomes  essential  that  the  application  first  read  the  relevant 
supplier  data  to  determine  which  case  applies.  Thus  Example_C  requires  three  SQL  state¬ 
ments.  (Since  it  is  necessary  to  read  the  initial  status,  it  is  possible,  and  simpler,  to  calculate 
the  updated  status  value  in  the  Ada  application.  This  would  eliminate  the  need  for  one  of  the 
two  update  procedures,  the  procedure  IncrStatus.  An  attempt  to  set  status  to  an  invalid 
value,  one  not  in  the  range  of  the  Status  domain,  would  then  be  trapped  in  the  Ada  appli¬ 
cation.  Example_C  has  been  designed  so  that  the  DBMS  will  trap  illegal  updates,  in  order  to 
illustrate  a  method  by  which  the  SAME  can  handle  that  phenomenon.)  The  text  of 
Example_C  is  found  in  Figure  8-14. 

A  new  abstract  domain,  increment,  has  been  defined  for  this  example.  This  domain  does 
not  describe  any  database  data,  but  it  does  describe  data  passed  across  the  abstract  inter¬ 
face.  (The  package  lncrement_Definition_Pkg  is  given  in  Figure  8-15.)  The  new  domain  has 
been  placed  in  a  domain  package  by  itself.  It  could  have  been  placed  in  a  domain  package 
with  other  domains,  had  there  been  any  reason  to  do  so. 

Although  only  the  _Not_Null  type  within  the  domain  definition  is  used,  the  domain  is  fully 
defined,  with  a  null  bearing  type  and  a  generic  subpackage  instantiation.  There  is  some  con¬ 
crete  benefit  from  that.  The  designer  may  be  certain  that  there  will  never  be  a  need  for  a 
null  Increment,  but  such  certainties  are  notoriously  fallible.  More  importantly,  for  uniformity, 
consistency,  and  clarity,  all  data  crossing  the  abstract  interface  must  be  of  a  type  defined 
within  an  abstract  domain  in  an  abstract  domain  package.  There  is  no  time  penalty  for  doing 
this,  but  there  is  a  space  penalty.  If  indeed  there  are  never  any  null  Increments,  then  the 
space  occupied  by  the  generic  subpackage  is  wasted.  (Some  compilers  may  be  intelligent 
enough  to  recover  the  wasted  space.)  If  the  space  is  available,  the  benefits  of  uniformity  are 
worth  the  price. 

The  AcquireSupplier  procedure  returns  an  entire  S  tuple,  even  though,  apparently,  only  the 
status  value  is  of  interest.  This  is  acceptable,  although  it  may  negatively  affect  performance. 
This  may  be  an  artifact  of  reuse.  It  is  likely  that  a  software  development  organization  writing 
database  applications  will  develop  procedures  for  accessing  single  tuples  by  key.  Such  pro¬ 
cedures  can  be  reused,  as  may  be  the  case  here. 

The  abstract  procedures  representing  the  two  SQL  update  statements  have  an  attached 
result  parameter  that  has  a  locally  defined  enumeration  type.  As  can  be  seen,  these  proce¬ 
dures  can  terminate  in  four  possible  ways:  successfully,  indicating  that  the  requested  up¬ 
date  occurred;  with  a  constraint  violation,  indicating  that  the  update  did  not  occur  due  to  the 
new  status’s  being  out  of  range;  with  a  permission  violation,  indicating  the  user  does  not 
have  permission  to  update  supplier  statuses;  and  with  no  record  found.  The  last  condition  is 
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a  logical  impossit  lity,  since  the  update  is  preceded  by  an  acquisition  of  the  record  to  be 
updated.  It  may  be  irgued  that  this  condition  should  not  be  returned  tc  the  application,  but 
rather  trigger  the  st  mdard  error-processing  path,  as  it  indicates  some  unrecoverable  error. 

The  Boolean-valued  function  Choose  filters  the  suppliers  based  on  a  static  property  con¬ 
tained  in  the  function  body.  This  function  is  admittedly  a  contrivance  designed  to  illustrate 
aspects  of  the  SAME’S  logical  processing.  Its  discussion  is  delayed  until  after  the  discussion 
of  the  abstract  module  body  for  Example_C.  That  code  can  be  found  in  Figure  8-16. 

The  two  update  procedure  bodies  in  Figure  8-1 6  are  essentially  identical,  differing  only  in 
the  concrete  procedure  which  they  call.  Their  function  is  to  analyze  the  SQLCODE  value 
returned  in  one  of  the  four  ailowab'e  cases.  Constraint  and  permission  violations  are  not 
thoroughly  covered  by  the  current  SQL  standard.  That  standard  describes  user  authoriza¬ 
tions,  but  does  net  describe  the  result  of  an  authorization  violation.  The  current  standard 
does  not  cover  data  integrity  constraints  at  all,  although  most  SQL  DBMSs  do.  Thus,  the 
SQLCODE  values  to  be  looked  for  are  dependent  upon  the  DBMS  in  use.  The  code  in 
Figure  8-16  is  designed  for  use  with  RTi's  Ingres  DBMS.  If  this  code  were  to  be  ported  to  a 
different  DBMS  the  constants  Constraint_Violation  and  Permission_Violation  would  have  to 
be  redefined.  (Notice  that  to  Ingres,  a  constraint  violation  is  signalled  as  a  no-record-found 
condition.  The  abstract  module  code  has  been  deliberately  written  to  check  for 
Constraint_Violation  first.  Had  this  code  been  written  for  some  other  DBMS  and  ported  to 
Ingres,  some  recoding  might  have  been  necessary.) 
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PROCEDURE  AcquiraSuppliar 
Sno_In  Char  (5) 

Sno_Out  Char  (5) 

SnaiM  Char  SnaiM  Indie  Smallint 
Statu*  Int  Status  Indie  Smallint 
City  Char  City_Indic  Smallint 
SQLCODE ; 

SELECT  Sno,  Snama,  Status,  City 
INTO  Sno_Out , 

Snam*  INDICATOR  Sn*ms_Indie, 

Status  INDICATOR  Status_Indic, 

City  INDICATOR  City_Indie 
FROM  S 

WHERE  Sno  =  Sno_In; 

PROCEDURE  InerStatus 
Incrsmsnt  Int 
Sno_In  Char  (5) 

SQLCODE; 

UPDATE  S 

SET  Status  =  Status  +  Incrsmsnt 
WHERE  S . Sno  =  Sno_In ; 

PROCEDURE  SstStatus 
Incrsmsnt  Int 
Sno_In  Char  ( 5 ) 

SQLCODE ; 

UPDATE  S 

SET  Status  =  Incrsmsnt 
WHERE  S  .  Sno  «=  Sno_In ; 

Figure  8-12:  The  SQL  Procedures  for  Example_C 
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With  Incrtnwnt  Def inition_Pkg,  Suppliers_De£mition_Pkg, 

City_Def inition_Pkg; 

Use  Increment  Def inition_Pkg,  Suppliers_Def inition_Pkg, 

City  Def inition_Pkg; 
package  Example_C_Module  IS 

type  Supplier_Record_Type  is  record 
Sno  :  SMO_Not_Null; 

SName  :  SNAME_Type; 

Statu*  :  Status_Type ; 

City  :  City_Type ; 

end  record; 

type  Opdate_Statu*_Result_Type  is  (Succeaa, 

Mo  Supplier, 

Constraint_Violated, 

Permia*ion_Denied) ; 

procedure  AcquireSupplier  (Sno_In  in  Sno_Not_Null; 

Supplier_Record  :  in  Out  Supplier_Record_Type; 
Found  :  OUt  Boolean)  ; 

procedure  IncrStatu*  (Sno  :  in  Sno_Not_Null; 

Increment  :  in  Statua_Increment_Not_Null; 

Result  :  OUt  Dpdate_Statu*_Reault_Type ) ; 

--  adds  Increment  (signed  quantity)  to  Status 

—  of  Supplier  Sno.  Result  is  Constraint_Violated  if 

—  updated  status  violates  constraint  on  Status .  Result  is 
—  No_Suppli*r  is  Sno  i*  not  in  database  or  its  Status 

—  is  Null .  Result  is  Success  if  the  Supplier 

—  with  number  Sno  has  had 

—  his  Status  incremented  by  the  value  of  Increment 

procedure  SetStatus  (Sno  :  in  Sno_Not_Null; 

Increment  :  in  Statu*_Increment_Not_Null; 

Result  ;  OUt  Opd*te_Status_Result_Type )  ; 

—  Sets  Status  of  Suppler  Sn^  to  Increment 
—  Result  is  Const£*int_Viol*t*d  if  updated  Status 

—  violates  constraint  (e.g.,  is  negative). 

—  Result  is  Mo  Supplier  if  Sno  is  not  in  database 

—  or  its  Status  is  rot  Mull.  Result  is  Success  if 

—  the  Supplier  with  number  Sno  has  had  hi*  Statu* 

—  set  to  the  value  of  Increment . 
end  Example_C_Module ; 

Figure  8-13:  The  Abstract  Module  for  Example_C 


CMU/SEI-89-TR-16 


103 


With  Suppliers_Definition_Pkg,  Parts_Daf inition_Pkg, 

QTY_Def inition_Pkg,  Incramanfc_Definition_Pkg,  Example  C_Modul« , 
S  QL_Ba  a  e_Type  s_P  leg  ; 

use  Suppliars_Def inition_Pkg,  Parts_Def inition_Pkg, 

QTY  Def inition_Pkg,  Increment_Def inition  Pkg,  Example_C  Module, 
S  QL_Base_Typa  a_P  k  g  ; 

separate  (Driver) 

procedure  Exampla_C  (Sno  :  Sno_Not_Null; 

Incrmant  :  StatuB_Incrsment_Not_Null)  Is 

—  A  filter  on  suppliers.  Serves  to  illustrate  SAME  logic, 
function  Choose  (A  Supplier  :  Suppliar_Racord  Typa) 
return  boolean  is  separate; 

—  The  diaplay  procadura  will  not  ba  ahowr 
procedure  Display_The_Line_C  (Maaaaga  :  SQL_Char_Not_Null) 
is  separate; 


begin 

declare 

—  Maaaagaa  to  ba  diaplayad  to  uaar  indicating  atatua  of  updata 
No_Suppliar_Mag  :  constant  SQL_Char_Hot_Mull  := 

"Tha  Suppliar  ”  £  SQL_Char_Not_Null (Sno) 

£  "  Doaa  Mot  Exist  in  tha  Database"; 
Conatraint_Violation  :  constant  SQL_Char_Not_Null  := 

"Tour  attamptad  atatua  modification  "  £ 

"violataa  databaaa  conatrainta”; 

Opdate_Successful  :  constant  SQL_Char_Not_Null  :  = 

"Statua  auccaaafully  updatad"; 

Not_Choaan  :  constant  SQL_Char_Not_Null  :  = 

"You  may  not  Opdata  tha  Status  of  Suppliar  "  £ 
SQL_Char_Not_null (Sno)  ; 

Parmiaaion_Danial  :  constant  SQL_Char_N ot_N ul  1  :  = 

"You  do  not  hava  pamiasion  to  updata  Suppliar  data"; 
Onknown_Erxor  :  constant  SQL_Char_Not_Null  :  = 

"Tha  Suppliar  "  £  SQL_Char_Not_Null (Sno)  £ 

"has  inexplicably  diaappaarad  from  tha  databaaa . "  £ 

"  Contact  a  aarvica  representative . " ; 

—  objacta  for  ccnorata  modula  communication 
Suppliar  :  Suppliar_Racord_Typa ; 

Exists  :  Boolaan; 

Raaults  :  Dpdata_Statua_Raault_Typa; 

begin 

AcquireSupplier (Sno,  Suppliar,  Exists) ;  —  gat  initial  statua 
ft  not  Exists  then 

Diaplay_Tha_Lina_C  (Mo_Suppliar_Mag)  ;  —  no  such  supplier 
eislf  Choose  (Suppliar)  then  —  filter  suppliers 

if  Ia_Mull (Suppliar . Statua)  then  —  decide  which  SQL  statement 
SatStatus (Sno,  Increment,  Results);  —  to  call 

else 

IncrStatus (Sno,  Increment,  Results) ; 

end  if; 

case  Results  is  —  tall  user  status  of  updata 

when  No_Supplier  => 

Display_The_Line  C (Unknown  Error) ; 
when  Constraint_Violated  => 

Display_The_Line_C (Constraint_Violation) ; 
when  Permission  Denied  => 

Diaplay_The_Line_C (Parmission_Danial) ; 
when  Success  s> 

Display_Tha_Lina_C (Update_Succesaful) ; 

end  case; 
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else 

Diaplay_The_Line_C (Not_Choa*n) ;  —  status  whan  filtered  out 

end  if; 

end; 

end  Example  C; 

Figure  8-14:  Example_C 

with  Suppli*ra_D*f inition_Pkg,  SQL_Int_Pkg; 

use  Suppli*ra_D*f inition_Pkg,  SQL_Int_Pkg; 

package  Incr*m*nt_D*finition_Pkg  is 

type  Statu*_Incr*m*nt_Not_Null  is  new  SQL_Int  Not  Null 
rang*  -SQL_Infc_Not_Null (Statua_Not_Null' Laat)  .. 

SQL_Int_Not_Null (Statua_Not_Null' Laat) ; 
type  Statua_Incr*m*nt_Typ*  is  new  SQL_Int; 
package  Statua_Incr*m*nt_Ope  is  new 

SQL_Int_Opa (Statue_Incr*ment_Type,  Statua_Increm*nt  Not  Null); 

end  Increment  Definition  Pkg; 

Figure  8-15:  The  Package  lncrement_Definition_Pkg 
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with  Conv*r«ion«,  SQL_Standard,  SQL_Con*nunications_Pkg, 

SQL  Database  Error  Pkg,  Example_Concret«  Module ; 

USe  Conversions,  SQL_Standard,  SQL_Consnunications_Pkg, 

SQL  Database_Error_Pkg; 
package  body  Example_c_Module  is 

package  Cone  renames  Ezample_Concrete_Module; 

use  SNAME_Ops,  Status_Ops,  City_Ops; 

Constraint_Violation  :  constant  :=  100;  —  implementation  defined 

—  the  value  of  SQLCODE 

—  when  an  update  would  violate 

—  a  constraint 

Permission  Violation  :  constant  : =  -1;  —  implementation  defined 

—  the  value  of  SQLCODE 

—  when  a  user  does  not  have 

—  update  permission 

procedure  AcguireSupplier  (Sno_IV»  :  in  Sno_Not_Null ; 

Supplier_Record  in  out  Supplier_Record  Type; 
Found  :  OUt  Boolean)  is 

Sname_c  :  Char (Sname_Not_Null' Range) ; 

Status_c  :  Int ; 

City_c  :  Char (City_Not  Null' Range); 

Snasne  Indie,  Status  Indie,  City_Indic  :  Indicator_Type ; 
begin 

Cone . Acquire Supplier (Char ( Sno_In) , 

Char (Supplier_Racord. Sno) , 

Sname_c,  Sname_Indic, 

Status_c,  Status_Indic, 

City_c,  City_Indic, 

SQLCODE) ; 

if  SQLCODE  in  Not_Found  then 
Found  :«=  False; 
elslf  sqlcode  /*  o  then 

Pxocees_Database_Error ; 
raise  SQL_Database_Error ; 

else 

Found  ;  *=  True; 

assign (Supplier_Record . Sname , 

SNAME  Base (Convert (Sname_c,  Sname_Indic) ) ) ; 
assign (Supplier_Record . Status, 

Status_Type (Convert  (Status_c,  Status_Indic) ) ) ; 
assign (Supplier_Record . City, 

CITY_Base (Convert (City_c,  City_Indic) ) ) ; 

end  If; 

end  AcguireSupplier; 

procedure  IncrStatus  (Sno  :  in  Sno_Not_Null ; 

Increment  :  in  Status_Increment_Not_Null; 

Result  :  OUt  Update_Status_Result_Type)  is 

begin 

Cone . IncrStatus (Int (Increment) , 

Char (Sno) , 

SQLCODE) ; 

If  SQLCODE  =  Conetraint_Violation  then 
—  update  refused;  constraints 
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Result  :=  Constraint  Violated; 
elsif  SQLCODE  =  Permission_Violation  then 

—  update  refused:  permission 
Result  :=  Permission  Denied; 

elsif  SQLCODE  in  Not_Found  then 

Result  :=  No_Supplier;  —  Sno  not  in  database 

—  or  Status  Null 

elsif  SQLCODE  /=  0  then  —  unrecoverable  error 

Prooess_Database_Error ; 
raise  SQL_Databaae_Error; 

else 

Result  : =  Success;  —  successful  conpletion 

end  If; 

end  IncrStatus ; 

procedure  SatStatua  (Sno  in  Sno_Not_Nul.l; 

Increment  :  in  Statue  Increment  Not  Null; 
Result  :  out  Opdate_Status_Result  Type)  is 
—  This  logic  is  identical  to  IncrStatus  except 
—  concrete  procedure  SetStatus  is  called 

begin 

Cone . SetStatus (Int (Increment) , 

Cbar (Sno) , 

SQLCODE) ; 

If  SQLCODE  =  Constraint_Violation  then 
--  update  refused:  constraints 
Result  :=  Constraint_Violated; 
elsif  SQLCODE  =  Permission_Violation  then 

—  update  refused:  permission 
Result  :=  Permission  Denied; 

elsif  SQLCODE  in  Not_Found  then 

Result  :=  No_Supplier;  --  Sno  not  in  database 

elsif  SQLCODE  /=  0  then  --  unrecoverable  error 
Process_Database_Error ; 
raise  SQL_Database_Error ; 

else 

Result  :*  Success;  —  successful  con^>letion 

end  If; 

end  SetStatus; 
end  Exan$>le  C  Module; 

Figure  8-16:  The  Abstract  Module  Body  for  Example_C 
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with  City_Dsf inition_Pkg;  use  City_D«finition_Pkg; 
separate  (Driver . Example  _C) 

tunction  Cbooss  (A_Suppli«r  :  Suppli«r_Record_Type)  return  boolean  is 

use  City_Ops; 
use  Charact.er_Set  ; 

begin 

—  this  vereion  reject*  any  supplier  known  to  be  in  Pittsburgh 
If  A_Supplier . City  =  With_Null ("Pittsburgh")  then 
return  false; 

else 

return  true; 
end  If; 
end  Choose; 


Figure  8-17:  Choose  -  Version  1 


with  City_Def inition  Pkg,  SQL_Boolean_Pkg; 
use  City_Definition_P)cg,  SQL_Boolean_Pkg; 

Separate  (Driver .Example_C) 

function  Choose  (A_Supplier  :  Supplier_Record_Type)  return  boolean  is 

use  City_Op* ; 

use  Character_Set ; 

begin 

--  this  version  reject*  any  supplier  that  might  be  in  Pittsburgh 

case  Equals (A_Supplier. City,  With_Null ( "Pittsburgh” ) )  is 
when  True  |  Unknown  => 
return  false; 
when  False  => 
return  true; 

end  case,- 
end  Choose; 

Figure  8-18:  Choose  -  Version  2 

Illustrations  of  Three-Valued  Logic 

This  section  concludes  with  a  discussion  of  the  Choose  function  in  Example_C.  As  men¬ 
tioned,  this  function  has  been  contrived  for  the  purpose  of  illustrating  logical  processing 
within  the  SAME.  Five  separate  versions  of  Choose,  illustrating  different  aspects  of  that 
processing,  will  be  presented.  The  first  two  versions  appear  in  Figures  8-1 7  and  8-18.  These 
two  versions  are  both  concerned  with  the  city  of  Pittsburgh.  In  the  first  version,  the  function 
returns  false  for  any  supplier  whose  city  value  is  Pittsburgh.  The  second  version  returns 
false  for  suppliers  whose  city  is  either  unknown  (null)  or  Pittsburgh.  This  version  needs 
visibility  to  SQL_Boolean_Pkg  in  order  to  have  the  enumeration  literals  in  the  case  alter¬ 
natives  correctly  identified.  The  first  version  deals  only  with  known  information,  with  the  abil¬ 
ity  to  establish  a  fact:  the  second  version  deals  with  uncertainty,  with  the  inability  to  disprove 
a  fact.  In  other  words,  the  version  in  Figure  8-1 7  looks  for  suppliers  whose  city  is  definitely 
Pittsburgh,  the  so-called  minimal  result:  whereas,  the  version  in  Figure  .  -18  looks  for  sup¬ 
pliers  whose  city  may  be  Pittsburgh,  the  so-called  maximal  result. 
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In  the  third  and  fourth  versions  of  Choose,  displayed  in  Figures  8-19  and  8-20,  suppliers  are 
selected  based  on  their  status  values.  The  third  version,  in  Figure  8-19,  resembles  the  first 
version,  in  Figure  8-17,  in  that  it  rejects  only  those  suppliers  whose  status  is  Known  to  not 
exceed  the  specified  value.  Similarly,  the  fourth  (Figure  8-20)  resembles  the  second  (Figure 
8-18),  in  rejecting  those  suppliers  whose  status  values  might  not  exceed  the  given  value. 
The  fourth  version  works  by  the  double  negation  principle;  suppliers  are  rejected  if  it  is  not 
known  that  their  status  values  exceed  the  given  value.  The  fourth  version  could  have  been 
coded  in  the  style  of  the  second  version,  using  a  case  statement  whose  alternatives  are 
guarded  by  literals  of  the  Boolean_with_Unknown  enumeration  type.  However,  the  second 
example  (Figure  8-18)  cannot  be  coded  in  the  style  of  the  fourth,  since  Ada  will  not  allow 
explicit  overloadings  of  the  negation  of  the  equality  operator. 

The  final  version  of  Choose,  shown  in  Figure  8-21,  exemplifies  mixed  mode  comparisons  for 
string  based  values  and  the  substring  operation.  This  version  rejects  suppliers  whose  name 
contains  their  city  as  a  substring.  Only  the  definite  information  version  is  shown.  Points  to 
be  noticed  about  Figure  8-21  are: 

•  The  search  excludes  the  sequence  of  trailing  blanks  in  the  supplier’s  name 
field. 

•  The  search  avoids  the  exception  constraint_error  in  the  Substring  function. 

This  and  the  previous  point  explain  the  upper  bound  on  the  for  loop. 

•  The  search  does  not  require  the  string  of  trailing  blanks,  if  any,  in  the  city  field 
to  be  present  in  the  name  field.  This  explains  the  length  parameter  in  the  Sub¬ 
string  function  call. 

•  It  is  not  necessary  to  actually  remove  the  trailing  blanks  from  the  City  field. 

•  For  the  comparison  to  be  syntactically  valid,  one  of  its  operands  must  be  con¬ 
verted  to  the  other’s  type.  The  city  operand  is  converted  to  the  type  of  suppliers’ 
names.  The  unconstrained  type,  SNAME_Base,  is  used.  Were  the  constrained 
type,  SNAME_Type,  used  here,  a  constrairit_error  would  be  raised  due  to  the 
conflict  in  discriminant  values,  i.  e.,  string  lengths. 
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separate  (Driver .Example_C) 

function  Choose  (A  Supplier  :  Supplier_Record  Type)  return  boolean  is 

use  Statu*_Ops; 
use  Character_Set; 

begin 

—  thi»  version  reject*  any  supplier 

—  whose  status  is  known  to  be  less  than  or  equal  to  20 

If  A_Supplier. Status  <=  WithJNull (20)  then 
return  false ; 

else 

return  true; 
end  If; 
end  Choose; 

Figure  8-19:  Choose  -  Version  3 

separate  (Driver . Rxample_C) 

function  Choose  (A_Supplier  :  Supplier_Reeord_Type)  return  boolean  is 

use  Status_Ops ; 
use  Character_Set ; 

begin 

—  this  version  rejects  any  supplier 

—  whose  status  is  not  known  to  be  greater  than  20 

If  not  (A_Supplier . Status  >  With_Null (20) )  then 
return  false  ; 

else 

return  true; 
end  lf; 
end  Choose ; 

Figure  8-20:  Choose  -  Version  4 
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with  City  Definition_Pkg,  Suppliers_Definition_Pkg; 
use  City_De£inition  Pkg,  Suppliers_De£inition_Pkg; 
separate  (Driver .Example  _C) 

function  Choose  (A_Supplier  :  Supplier_Record_Type)  return  boolean  is 
use  City_Ops,  SNAME_Ops; 
begin 

—  this  version  rejects  any  supplier  whose  name  contains 

—  its  city  as  a  substring 
for  i  in 

l  . . 

(Onpadded_Length (A_Supplier . Sname)  - 

(Onpadded_Length (A  Supplier . City )  -  1)) 

loop 

if  Substring (A_Supplier . Sname,  i,  Onpadded_Length (A_Supplier . City) ) 

SNAME_Base ( A_Supplier . City)  then 
return  False ; 

end  if; 
end  loop; 
return  True; 
end  Choose; 

Figure  8-21 :  Choose  -  Version  5 
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9.  Advanced  DBMS  Applications 

This  chapter  deals  with  specialized  applications  of  SQL  DBMS  technology;  in  particular,  with 
applications  that  require  dynamic  SQL  services  and  those  Ada  DBMS  applications  which 
use  Ada  tasking.  It  should  be  noted  that  ANSI  standard  SQL  [2]  supports  neither  of  these 
features.31  There  are  DBMS  implementations  on  the  market  which  provide  support  for  one 
or  both  of  these  facilities.  The  discussion  in  this  section  cannot  take  the  details  of  these 
implementations  into  account.  The  reader  will  need  to  adapt  the  methods  of  this  section  to 
the  target  DBMS. 

A  second  note  of  caution  must  be  introduced  into  this  section.  Whereas  the  ideas  in  other 
sections  of  these  guidelines  have  been  verified,  and  all  of  the  code  has  been  compiled  and 
executed,  the  author  did  not  have  at  his  disposal  a  DBMS  which  supported  either  of  the 
classes  of  applications  discussed  in  this  section.  Therefore,  the  code  presented  here  has 
not  been  executed,  although  it  has  been  compiled,  and  the  ideas  have  not  been  directly 
tested  against  any  DBMS. 

9.1.  Dynamic  SQL 

As  has  been  shown  in  previous  sections,  SQL  statements  can  take  runtime  parameters. 

This  parameterization  is  limited  to  those  parts  of  an  SQL  statement  in  which  a  constant  may 
appear.  In  the  examples  of  Chapter  8,  SQL  statements  were  parameterized  with  Supplier 
and  Part  numbers.  If  a  needed  DBMS  service  is  to  be  parameterized  by  something  other 
than  a  constant,  this  can  be  done  with  dynamic  SQL.  If,  for  example,  an  update  application 
allows  for  the  modification  of  various  sets  of  dynamically  specified  columns  using  various 
sets  of  dynamically  specified  update  expressions  and  various  sets  of  dynamically  specified 
search  conditions,  it  may  choose  to  use  dynamic  SQL.  If  the  amount  of  variation  is  very 
small,  it  may  be  preferable  for  the  application  designer  to  produce  a  small  set  of  static  SQL 
update  statements  and  choose  the  statement  to  execute  at  runtime.  Dynamic  SQL  applica¬ 
tions  are  harder  to  write  than  static  SQL  applications  and  add  runtime  overhead.  A  good 
heuristic  to  follow  is  to  avoid  the  use  of  dynamic  SQL  whenever  feasible. 

A  full  description  of  dynamic  SQL  is  inappropriate  for  these  guidelines.  There  follows  a  brief 
description  of  dynamic  SQL  based  on  the  proposals  in  [3]. 

The  SQL  statement  to  be  dynamically  executed  is  created  by  the  application  as  a  character 
string.  This  string  is  presented  to  the  DBMS  as  the  operand  of  a  prepare  statement.  If  the 
statement  is  not  a  select  statement,  i.e.,  if  it  is  an  insert,  update,  delete  or  one  of  a 
handful  of  other,  bookkeeping  statements  (see  [3]),  it  may  then  be  EXECUTEd.  A  cursor  must 
be  declared  for  select  statements.  Once  declared,  the  cursor  is  OPENed,  FETCHed  and 
CLOSEd  as  in  static  SQL  Thus,  the  mental  model  of  dynamic  SQL  operation  is  very  much 
the  same  as  for  static  SQL. 

Dynamic  SQL  applications  can  be  placed  along  a  continuum  whose  end  points  may  be 
called  “fully  dynamic"  and  “slightly  dynamic.”  Fully  dynamic  applications  are  generalized 
system  software  utilities.  They  typically  provide  an  ad  hoc  browsing  and  updating  capability. 


31The  follow-on  ANSI  standard  [3]  has  support  for  dynamic  SQL. 
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(Most  SQL  DBMS  offer  an  interactive  version  of  SQL.  However,  SQL  is  probably  not  a  good 
end  user  language.)  These  applications  are  often  supplied  by  the  DBMS  vendor  or  by  third 
parties  and  are  written  with  no  knowledge  of  the  schema  of  the  database  against  which  they 
execute.  Slightly  dynamic  applications  offer  more  restricted  services  to  their  users.  They  are 
written  with  full  knowledge  of  the  target  database  schema,  its  semantics,  and  the  abstract 
domains  involved. 

The  central  distinction  between  static  and  dynamic  SQL  statement  execution  is  the  manner 
in  which  runtime  parameters  are  passed.  SQL2  offers  three  distinct  methods  of  passing 
parameters  to  dynamically  prepared  statements.  Each  dynamic  statement32  has  a  using 
clause  whose  operand  specifies  the  manner  in  which  parameters  are  being  passed.  In  the 
simplest  case,  this  operand  is  a  list  of  identifiers.  This  alternative  can  and  should  be  used 
whenever  the  number  and  type  of  the  parameters  of  the  statement,  i.e.,  its  parameter 
profile,  do  not  vary  and  the  dynamically  varying  parts  of  the  statement  lie  elsewhere  (e.g.,  in 
the  use  of  these  parameters  in  a  search  condition).  Such  applications  lie  at  the  slightly 
dynamic  end  of  the  continuum.  When  the  list  of  identifiers  option  of  the  using  clause  ap¬ 
pears,  the  abstract  procedure  declaration  corresponding  to  the  dynamic  statement  is  iden¬ 
tical  to  its  static  counterpart  in  its  use  of  row  records,  abstract  domain  types,  and  result 
parameters.33 

Example 

Suppose  a  program  wishes  to  execute  an  UPDATE  statement  which  always  takes  a  part  num¬ 
ber,  a  color,  and  a  weight,  sometimes  updating  the  color  and  sometimes  updating  the 
weight.  Assuming  this  is  to  be  done  with  dynamic  SQL,  two  dynamic  statements  are 
needed:  prepare  and  execute.  (In  practice,  an  execute  immediate,  which  performs  both 
functions,  could  be  used.  Two  statements  are  used  here  for  purposes  of  illustration.)  The 
module  procedures  are: 

PROCEDURE  STMT_PREP 

STMT_TO_PREP~CHAR ( 100 ) 

SQLCODE; 

PREPARE  ST  FROM  STMr_TO_PRZP ; 

PROCEDURE  UP D ATE_EXZ C 
PNO  CHAR  (S) 

WEIGHT  HIT  WEIGHT_INDIC  SMALL  HIT 
COLOR  CHAR  (6)  COLOR_INDIC  SMALL INT 

EXEC  ST  USING  PNO, 

WEIGHT  INDICATOR  WZIGHT_INDIC, 

COLOR  INDICATOR  COLOR  INDIC; 


32Dynamic  SQL  statements,  e.g.,  prepare,  execute,  dynamic  open,  and  dynamic  fetch,  are  distinct  from 
dynamically  prepared  SQL  statements,  e.  g.,  SELECT,  update,  insert.  The  dynamic  SQL  statements  are  those 
which  are  executed  by  a  dynamic  SQL  program  to  accomplish  the  database  operations  specified  by  the  dynami¬ 
cally  prepared  SQL  statements. 

33SQL2's  notions  of  extended  statement  identifier  and  extended  cursor  name,  to  be  described,  are  runtime 
parameters  which  may  be  needed  at  the  abstract  interface,  even  in  this  case. 
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The  abstract  module  procedure  declarations  corresponding  to  these  module  procedure  are: 

procedure  Stmt_Prep  ( Stmt_To_Prap  In  SQL_Chax_Not_Null)  ; 

procedure  Update_Exac  (Pno  in  Pno_Not_Null; 

Weight  :  in  Waight_Typa; 

Color  In  Color  Type) ; 

Result  parameters  can,  of  course,  be  attached  to  either  or  both  of  these  procedures. 

Applications  which  require  SQL  statements  whose  parameter  profiles  vary  dynamically  must 
be  '‘polymorphic,"  that  is,  able  tc  deal  with  a  variety  of  types  at  runtime.  Although  Ada  is  not 
a  polymorphic  programming  language,  the  Ada  variant  record  construct  can  be  used  to  sim¬ 
ulate  polymorphism,  provided  that  the  set  of  possible  runtime  types  is  known  at  compile 
time.  Furthermore,  each  variant  will  typically  require  path  segments  unique  to  it.  It  is  best  if 
the  number  of  types  is  kept  small. 

SQL2  offers  two  methods  of  passing  parameters  to  dynamically  prepared  statements  whose 
parameter  profiles  vary  dynamically.  Both  methods  are  based  on  the  cdynamic  using 
descriptor  area  stiucture>  or  SQLDA.  In  the  first  of  the  two  methods  the  SQLDA  is  allocated 
by  the  application  program  and  exists  in  its  name  space.  In  the  second  method,  the  SQLDA 
is  allocated  by  the  DBMS  and  exists  in  its  name  space.  In  Ada  terms,  the  distinction  is  that 
between  visible  and  private  declarations  of  the  SQLDA  type.  The  first  of  these  alternatives, 
the  visible  SQLDA,  will  be  described  first,  as  the  second  alternative,  the  functional  approach, 
is  defined  in  terms  of  it. 

The  definition  of  the  SQLDA  structure  in  PL/I  can  be  found  in  Figure  9-1 .  The  ANSI  proposal 
does  not  allow  this  structure  in  Ada.  This  is  subject  to  change  before  the  standard  is  ap¬ 
proved  and,  of  course,  there  are  no  implementations  conformant  with  the  SQL2  proposal.  As 
was  mentioned,  the  reader  will  need  to  adapt  the  discussion  in  this  section  to  the  target 
DBMS  in  any  case.  A  proposed  definition  for  an  SQLDA  in  Ada  appears  in  Figure  9-2.  The 
package  SQL_Standard_Dynamic  is  like  the  package  SQL_Standard  in  that  it  describes 
data  crossing  the  concrete  interface. 

DCL  1  SQLDA 

2  SQLN  BIN  FIXED, 

/*  max  nbr  of  paramatars*/ 

2  SQLD  BIN  FIXED, 

/*  actual  nbr  of  paxamatars  */ 

2  SQLVAR  (SQLSIZE  REFER  (SQLN) ) , 

3  SQLDATA  PTR, 

/*  points  to  tha  data  */ 

3  SQLIND  PTR, 

/*  points  to  tha  indicator  para  */ 

3  SQLTYPE  BIN  FIXED, 

/•intagar  ancoda  of  typa  */ 

3  SQLNULLABLE  BIN  FIXED, 

/*  is  thara  an  indicator  parm?  */ 

3  SQLLEN  BIN  FIXED, 

/*  charactar  langth,  numaric  pracision  */ 

3  SQLSCALE  BIN  FIXED, 

/•  numaric  scala  */ 

3  SQLNAME  CHAR  (k)  VAR; 

/*  column  nama  if  applicabla  */ 

DCL  SQLSIZE  BIN  FIXED; 

Figure  9-1:  SQLDA  in  PL/I 
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The  implementation-specific  type  SQL_Dynamic_Datatypes_Base  is  used  to  choose  the  ap¬ 
propriate  integer  type  as  defined  by  the  DBMS.  The  constants  of  this  type,  Dynamic_Char, 
etc.,  define  the  integer  encoding  of  types  as  specified  by  ANSI  [3],  The  constant 
Not_Specified  is  used  as  the  default  for  the  discriminant  of  the  SQL_Dynamic_Parame?er 
type.  The  subtype  SQL_Dynamic_Datatypes  is  used  as  the  type  of  the  discriminant  to  ob¬ 
viate  the  need  for  an  others  variant. 

The  type  of  the  SQLDATA  component  of  the  SQLVAR_Component_Type 
(SQL_Dynamic_Parameter)  is  a  variant  record  of  access  types.  The  objects  accessed  by 
these  variants  are  of  types  declared  in  SQL_Standard  (or  the  not  null  decimal  type  in 
SQL_Decimal_Pkg).  The  SQLLEN  and  SQLSCALE  fields,  which  give  length,  precision,  and 
scale  information,  are  no  longer  present  as  fields,  but  are  now  attributes  (or  discriminants)  of 
the  accessed  objects. 

The  dynamic  SQL  describe  statement  takes  a  statement  identifier  and  an  SQLDA  object 
and  fills  in  the  type  information  in  the  SQLDA  from  the  prepared  statement  identified  by  the 
identifier.  When  issued  in  conjunction  with  the  definitions  of  Figure  9-2,  the  describe  state¬ 
ment  must  also  allocate  the  space  for  the  values  of  the  dynamic  parameters  described  by 
each  SQLVAR_Component_Type  object,  in  order  to  return  length,  precision,  and  scale  infor¬ 
mation.  The  values  themselves  may  be  left  undefined  by  describe.  This  behavior  is  slightly 
different  from  the  behavior  of  describe  in  [3],  Section  12.7. 

The  types  Extended_Cursor_Type  and  Extended_Statement_Type  are  used  for  the 
<extended  cursor  name>  and  <extended  statement  identifier  of  SQL2  [3].  Briefly,  the  con¬ 
nection  between  dynamic  statements  operating  on  a  dynamically  prepared  statement  (e.g., 
prepare  and  execute)  is  via  a  <statement  identifier  which  may  be  either  a  constant  or  a 
variable.  In  the  example  given  earlier,  the  token  ST  is  a  constant  statement  identifier. 
Similarly,  the  connection  between  dynamic  open,  close,  and  fetch  and  the  prepared  select 
statement  on  which  they  operate  is  via  a  <cursor  identifier,  which  may  be  either  a  constant 
or  a  variable.  (When  a  cursor  is  a  runtime  variable,  a  <dynamic  declare  cursor  statement 
must  be  executed  to  form  the  connection  between  the  prepared  select  statement  and  the 
cursor.)  An  object  containing  an  extended  statement  identifier  has  type 
Extended_Statement_Type;  an  object  containing  a  dynamic  extended  cursor  has  type 
Extended_Cursor_Type. 
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With  SQL_Standard,  SQL_Decimal_Pkg; 
use  SQL  Standard,  SQL  Decimal  PJcg; 
package  SQL  Standard_Dynamic  is 

type  Extended_Curaor_Type  is  implementation  defined; 

type  Extended_statement_Type  Is  implementation  defined; 

type  SQL_Dynamic_Datatypa*_Ba««  is  range  implementation  defined; 

Maybe_Null_Indic  Constant  Indicator  Type  :  =  1; 

—  value  of  SQLNULLABLE  if  nulls  allowad 
subtype  Null_Indication  is  Indicator  Type  range 
Indicator_Typs' Pirat  ..  -1; 

--  value  of  indicator  if  value  is  null 

—  types  to  describe  column  names 
SQL_Column_Name_Length  :  constant  :=  18;  —  set  in  SQL2  standard 
Subtype  SQL_Column_Name_Length_Type  is 

positive  range  1 .  .  SQL  Column  Name  Length; 

SUOtype  SQLNAME_Type  is  Char  ( SQL_Column  Name  Length  Type)  ; 

—  These  constants  capture  the  encoding  of  SQL  Types  as  integers 

—  as  given  by  SQL2 . 

Not_Specif ied  :  constant  SQL_Dynamic_Datatypes_Baoe  :=  0; 

Dynamic_Char  :  constant  SQL  Dynamic  Datatypes  Base  ;=  1; 

Dynamic  Numeric  :  constant  SQL  Dynamic  Datatypes  Base  :  =  2; 

Dynamic_Decimal  :  constant  SQL_Dynamic_Datatypes_Base  :=  3; 

Dynamic_Int  :  constant  SQL_Dynamic_Datatypes  Base  :=  4; 

Dynamic_Smallint  ;  constant  SQL_Dynamic_Datatypes_Base  ;  =  5  ; 

Dynamic_Float :  Constant  SQL_Dynamic_Datatypes  Base  :  «=  6; 

Dynami c_Re al  :  Constant  SQL_Dynamic_Datatypes_Base  :=  7; 

Dynamic_Double_Precision  :  constant  SQL_Dynamic_Datatypes_Base  :=  8; 

subtype  SQLJDynamicJDatatypes  is  SQL_Dynamic_Datatypes_Base 
range  Not_Specified  . .  Dynamic_Double_Precision; 

—  access  types  for  components  of  SQL_Dynamic_Parameter 
type  Char_Access  is  access  Char; 

type  Decimal_Access  Is  access  SQL_Decimal_Not_Null; 
type  Int_Access  is  access  Int  ; 
type  Smallint_Access  is  access  Smallint; 
type  Real _ Access  is  access  Real ; 

type  Double_Precision_Access  is  access  Double  Frecision; 

type  SQL_Dynamic_Parameter  (SQLTYPE  :  SQL_Dynamic_Datatypes  :=Not_Specified) 
is  record 

case  SQLType  is 

when  Not_Specified  «> 
null  ; 

When  Dynamic  Char  => 

Char_Value  :  Char  Access; 
when  Dynamic  Decimal  |  Dynamic  Numeric  =  > 

Decimal  Value  Decimal  Access; 
when  Dynamic  Int  => 

Int_Value  :  Int  Access; 

When  D yn ami c_Smal lint  => 

Smallint_Value  :  Smallint_Access; 
when  Dynamic_Real  => 

Real_Value  :  Real_Access; 
when  Dynamie_Double_Precision  |  Dynamic_Float  => 

Double_Precision_Value  :  Double_Precision_Access ; 
end  case; 
end  record 

type  SQLVAR_Co«nponent_Type  is  record 
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SQLDATA  :  SQL_Dyn*mic_P»raro«t«r ; 

SQLNPT.TART.E  :  Indic*tor_Typ*  ; 

SQLIND  :  Indic»tor_Typ« ; 

SQLNAMEL  :  SQL_Column_Naro«_L«ng-th_Typ«; 

SQLNAME  :  SQLNAME_Typ«  ; 
end  record ; 

type  SQLVAR_Typ«  is 

array  (Int  range  <>)  Of  SQLVar_Compon«nt_Typ«  ; 

type  sqida  (sqln  :  Int)  is  record 
SQLD  :  Int; 

SQLVAR  :  SQLVAR_Typ*  (1  . .  SQLN) ; 

end  record; 

end  SQL  Standard_Dynaai c ; 

Figure  9-2:  The  Package  SQL_Standard_Dynamic 
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The  package  SQL_Standard_Dynamic  is  like  the  package  SQL_Standard  in  describing  data 
at  the  level  of  the  concrete  interface.  Before  describing  an  abstract  interface  for  dynamic 
SQL,  it  is  first  necessary  to  consider  what  the  goals  of  an  abstract  interlace  design  for 
dynamic  SQL  should  be. 

As  mentioned  earlier,  fully  dynamic  SQL  applications  are  general  system  software  support¬ 
ing  ad  hoc  user  interactions.  As  such,  these  programs  are  independent  of  any  database 
schema,  which  is  to  say,  of  the  semantics  of  the  stored  data.  These  programs  do  not  deal 
with  Part  Numbers,  Supplier  Names,  Weights,  etc.  They  deal  with  character  strings,  in¬ 
tegers,  etc.  For  this  reason,  the  suggested  definition  of  an  abstract  SQLDA  in  Figure  9-3 
does  not  allow  for  user  defined  types.  However,  fully  dynamic  SQL  applications  can  be  pro¬ 
vided  with  the  standard  SAME  treatment  of  null  values  and  the  standard  SAME  treatment  of 
database  exceptional  conditions. 

The  package  SQL_Dynamic_Pkg  in  Figure  9-3  presents  a  set  of  abstract  types  closely 
modeled  on  the  set  of  concrete  types  in  SQL_Standard_Dynamic.  The  underlying,  "scalar” 
types  have  been  changed  to  types  suitable  for  an  abstract  interface.  These  types  are  de¬ 
fined  in  the  abstract  domain  package,  SQL_Base_Types_Pkg,  which  was  introduced  in 
Figure  3.8.  The  types  of  the  objects  accessed  by  components  of  SQL_Dynamic_Parameter 
in  SQL_Dynamic_Pkg  are  all  of  null  bearing  types.  It  is  possible  to  introduce  the  non-null 
bearing  types,  or  a  set  of  abstract  types,  into  this  list  of  components,  but  at  the  expense  of 
increased  application  complexity.  Each  variant  of  SQL_Dynamic_Parameter  will  require  an 
execution  path  segment  of  its  own.  There  is  good  reason  to  keep  the  number  of  such 
variants  small. 
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with  SQL_Base_Types_Pkg,  SQL_Standard_Dynamic; 
use  SQL_Base_Types_Pkg; 
package  SQL_Dynamic_Pkg  is 

These  next  definitions  deal  with  names  of  columns 
subtype  SQL_Column_Name_Length_Type  is 

positive  range  1 . . SQL_Standard  Dynamic . SQL_Column_Name_Length; 
subtype  SQLNAME_Type  is  SQL_Char_Not_Null  (SQL_Column_Nama_Length_Type)  ; 

—  Tha  discriminant  is  now  an  anumaration  type 
type  SQL_Dynamic_Data types  is 

(Not_Specified, 

Dynamic_Char,  Dynamic_Dacimal , 

Dynamic_lnt ,  Dynamic_Smallint , 

Dynamic_Real,  Dynamic_Double_Precision) ; 

—  access  types  access  null  bearing  types  in  Base_Type_Pkg 
type  Char_Access  is  access  SQL_Char_Typa  ; 

type  Decimal_Access  is  access  SQL_Decimal_Typa; 
type  Int_Access  is  access  SQL_Int_Type; 
type  Smallint_Accees  is  access  SQL_Smallint_Type; 
type  Real_Access  IS  access  SQL_Real_Type ; 

type  Double  Precision_Access  is  access  SQL  Double_Precision_Type; 


type  SQL_Dynamic_Parameter  (SQL TYPE  : SQL_Dynamic_Datatypes  :=  Not_Speci£ied 
is  record 

case  SQLType  is 

when  Not_Specified  => 
null ; 

when  Dynamic_Char  => 

Ch*r_Value  :  Char_Accee» ; 
when  Dynamic_Decimal  => 

Decimal_Value  :  Decimal  Access; 

When  Dynamic_Int  *=> 

Int_Value  :  Int_Accaas ; 
when  Dynamic_Smallint  => 

Smallint_Value  :  Smallint_Accees ; 

when  Dynamic _ Real  «> 

Real_Value  :  Raal_Access ; 
when  Dynamic_Double_P reels ion  => 

Double  Precision  Value  :  Double  Precision  Access; 
end  case; 
end  record; 

type  SQLVAR_Component_Type  is  record 
SQLDATA  :  SQL_Dynamic  Parameter; 

SQLNAMEL  :  SQL_Column  Name_Length_Type ; 

SQLNAME  :  SQLNAME_Type; 

end  record; 

type  SQLVAR_Type  is 

array  (SQL_Int_Not_Null  range  O)  of  SQLVa_r_Coinponant  Type; 

type  sqlda  (sqln  :  SQL_lnt_Not_Null)  Is  record 
SQLD  :  SQL_I nt_Not_Nul 1 ; 

SQLVAR  :  SQLVAR_Type  (1  . .  SQLN) ; 
end  record  ; 
end  SQL  Dynamic_Pkg; 

Figure  9-3:  The  Package  SQL_Dynamic_Pkg 
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With  the  definitions  of  Figures  9-3  and  9-2  at  hand,  it  is  possible  to  write  an  abstract  module 
supporting  a  dynamic  application,  The  module  allocates  and  maintains  a  local  object  of  the 
concrete  SQLDA  type,  as  defined  by  the  package  SQL_Standard_Dynamic  in  Figure  9-2, 
and  exports  to  the  application  subprograms  which  take  parameters  of  the  abstract  SQLDA 
type,  given  by  Figure  9-3.  The  module  then  translates  between  the  two  formats  on  each 
subprogram  call.  Although  such  modules  are  possible,  they  may  not  be  desirable,  partic¬ 
ularly  when  built  for  a  DBMS  which  does  not  directly  support  either  SQLDA  type.  (Of  course, 
there  are  no  DBMSs  which  support  these  types  at  this  time.)  A  module  which  operates  in 
this  way  requires  an  excessive  amount  of  data  movement.  The  information  in  the  SQLDA 
would  first  be  stored  in  an  SQLDA  structure  local  to  the  DBMS  (probably  in  either  C  or  PL/I, 
the  only  languages  currently  supporting  an  SQLDA  in  SQL2),  translated  to  the  concrete  Ada 
SQLDA,  and  then  translated  to  the  abstract  SQLDA.  These  translations  are  done  field  by 
field.  Since  the  purported  advantage  of  an  SQLDA  structure  is  runtime  efficiency,  the  over¬ 
head  of  these  translations  is  unacceptable.  The  remaining  alternative  to  dynamic  parameter 
passing,  the  functional  approach,34  eliminates  much  of  this  data  translation. 

The  functional  approach  treats  the  SQLDA  as  a  private  type  declared,  from  the  application 
program's  point  of  view,  behind  the  abstract  interface.  The  application  program  allocates 
objects  of  the  SQLDA  type  using  an  SQL-defined  allocation  procedure  whose  syntax  is: 

ALLOCATE  SQLDESCRIPTOR  <sqlda  descriptor  name> 
with  max  <occurrences> 

where  <sqlda  descriptor  name>  is  a  character  string  parameter  and  <occurrences>  is  an 
integer  parameter.  This  statement  appears  at  the  abstract  interface  as  the  following  proce¬ 
dure  declaration:35 

procedure  Allocate  (SQLDA_Nam®  :  SQL_Char_Not_Null ; 

Max  :  SQL_Int_Not_Nuir)  ; 

A  call  to  this  procedure  having  the  form: 

Allocat* (SQLDA_Nam«  =>  "SQLDA_Ob j«ct" , 

Max  =>  10) ; 

creates  an  SQLDA  structure  with  10  occurrences  of  the  SQLVAR  component  (i.e.,  an  SQLN 
value  of  10).  This  structure  can  be  referenced  by  the  name  "SQLDA_Object”  as  in  the  pro¬ 
cedure  call: 

Daallocat®  (SQLDA_Nam»  =>  " SQLDA_Ob j act ” ) ; 

which  calls  a  procedure  defined  by  the  SQL  syntax: 

DEALLOCATE  SQLDESCRIPTOR  <sqida  descriptor  name> 

There  is  no  need  for  more  than  one  Allocate  or  Deallocate  statement  in  any  module. 

The  type  information  within  an  SQLDA  is  supplied  as  the  result  of  a  describe  (or  describe 
input)  statement.  These  statements  take  a  prepared  statement  identifier  and  an  SQLDA 
object  name.  (This  information  can  also  be  modified,  to  within  implementation-defined  limits, 


-wThe  functional  approach  does  not  appear  in  [3],  It  is  contained  in  an  accepted  change  to  SQL2,  which  can 
be  found  in  [10],  The  ensuing  discussion  is  based  on  [10],  which  may  differ  from  the  description  of  the  functional 
approach  that  will  appear  in  »he  final  standard.  The  differences  should  be  minor  and  should  not  affect  an  abstract 
interface  providing  a  functional  approach  to  an  Ada  application. 

35The  Ada  code  in  these  following  examples  uses  types  in  SQL_Base_Types_Pkg.  It  may  be  desirable  to  use 
specially  designed  types,  declared  in  a  package  similar  in  purpose,  but  not  design,  to  SQL_Dynamic_Pkg,  for  the 
parameters  in  these  examples. 
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by  an  application,  thereby  effecting  runtime  data  conversion.)  Since  the  SQLDA  is  itself  hid¬ 
den,  two  functions,  GET  and  SET,  are  provided  to  access  or  modify  me  type  information  and 
the  values  of  the  parameters.  These  functions  have  two  forms  which  are  described  by  the 
following  combined  syntax: 

(GET  |  SET)  <sqlda  descriptor  name> 

[VALDES  csqtvar  number>]  <parameter  associations> 

The  <parameter  associations>  determine  what  information  is  to  be  extracted  from  (or  set 
into)  the  SQLDA.  The  form  without  the  VALUES  <sqlvar  number>  phrase  is  used  to  access 
the  SOLD  field,  which  determines  the  actual  number  of  parameters  used  by  the  dynamic 
statement.  Thic  is  the  only  field  of  an  SQLDA  which  is  not  a  subcomponent  of  the  SQLVAR 
component.  The  form  with  the  VALUES  phrase  accesses  suocomponents  of  the  SQLVAR 
component  with  index,  relative  to  one,  of  <sqlvar  number>. 

Within  [10],  the  <parameter  associations>  are  of  the  form  <parameter>  =  <identifier>  where 
<identifier>  is  the  name  of  an  SQLDA  field  as  shown  in  the  PU1  descnption  in  Figure  9-1 . 
(When  VALUES  is  absent,  only  SQLD  may  appear  as  an  <identifier>.)  Notice  that  the  GET 
(SET)  statement  is  not  itself  dynamically  preparable;  therefore  calls  to  these  statements 
have  parameter  profiles  that  can  be  determined  at  compile  time. 

Figure  9-4  contains  fragments  of  a  "fully  dynamic”  Ada  application  using  the  functional  inter¬ 
face.  The  example  is  based  on  [1 0].  The  app'ication  is  fully  dynamic  in  that  it  uses  the  data 
types  in  SQL_Base_Types_Pkg. 

The  abstract  module  used  by  the  program  in  Figure  9-4  contains  the  procedure  declarations 
for  the  SQL  statements  which  implement  the  functional  approach  to  dynamic  parameter 
passing.  It  is  not  essential  that  the  concrete  interface  used  by  the  abstract  module  also  im¬ 
plement  the  functional  approach;  an  SQLDA-based  concrete  interface  is  permissible.  The 
decision  can  be  made  on  performance  grounds  alone.  The  abstract  module  retains  respon¬ 
sibility  for  null  value  encapsulation  and  SQLCODE  processing.  (SQLCODE  processing  is 
not  explicitly  used  in  Figure  9-4,  in  order  to  control  its  size.  Comments  indicate  what  might 
be  done  in  a  realistic  setting.)  The  procedure  Set_SQLDATA  (Get_SQLDATA)  gives  values 
to  (accepts  values  from)  the  DBMS.  These  procedures  have  overloaded  declarations  in  the 
abstract  module,  one  declaration  for  each  of  the  null  beanng  types  in  Weak_Types_Pkg. 

The  abstract  module  procedure  bodies  are  responsible  for  processing  the  null  value.  For 
example,  the  body  of  a  Set_SQLDATA  procedure  might  be: 

If  I«_Null (SQLDATA)  then 

Cone. S«t_SQLNull (SQL VAR_Nbr  =>  SQLVAR_Nbr, 

SQLDA_Nam«  =>  SQLDA_Nam«, 

SQLNOLLABLE  =>  Maybe_Null_Indic , 

SQLIND  =>  Null_Indicat±on '  Last)  ; 

else 

Cone. S«t_SQLDATA( SQL VAR_Nbr  =>  S  QL  VAF.  _Nb  r , 

SQLDA _ N arr,«  =>  SQLDA_Nain«, 

SQLLHD  =>  0, 

SQLDATA  =>  SQLDATA)  ; 

end  If; 

Similarly,  the  Get_SQLDATA  procedure  needs  a  concrete  Get_SQLNull  procedure  to  deter¬ 
mine  if  an  output  value  is  null.  These  are  examples  of  concrete  procedures  which  do  not 
appear  at  the  abstract  interface.  Generally,  that  is  to  say,  in  static  SQL  applications,  there 
are  no  such  procedures.  (Note:  In  the  above  if  statement,  the  object  Maybe_Null_lndic  and 
the  subtype  NulIJndication  are  as  defined  in  the  package  SQL_Standard_Dynamic  shown 
in  Figure  9-2.) 
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It  is  possible  to  envision  an  abstract  module  and  application  program  which  are  less  fully 
dynamic  and  use  abstract  domains  for  parameter  values.  Dynamic  SQL  requires  the  data¬ 
base  to  access  its  data  dictionary  at  runtime.  This  processing  could  be  extended  tu  access 
an  Ada  data  dictionary  as  well.36  This  would  allow  the  application  program  access  to  the 
abstract  domain  of  the  parameters.  However,  such  access  would  increase  the  complexity  of 
the  application  and  the  runtime  overhead  of  the  abstract  module.  It  is  unclear  whether  the 
benefits  of  abstract  typing  outweigh  the  costs,  for  dynamic  applications.  (Note:  If  the  abstract 
domain  definitions  are  used  to  constrain,  via  range  constraints,  database  objects  in  a  man¬ 
ner  which  is  not  also  supported  by  the  DBMS,  then  fully  dynamic  update  programs  which  do 
not  use  the  abstract  domain  definitions  may  violate  database  constraints.) 


36As  mentioned  in  the  introductory  chapter,  the  SAME  -  Design  Committee  is  working  on  a  language  for 
automation  of  SAME  application  development.  The  processor  for  this  language,  whatever  its  final  form,  will 
certainly  need  an  Ada  data  dictionary. 


CMU/SEI-89-TR-16 


123 


Max_SQLVAR  constant  :=  10;  —  this  limit  on  SQLVAR  occurrences  is 

—  a  property  of  the  application  and  of 
--  the  DBMS  implementation 

Input  SQLDA  :  constant  SQL_Char_Not_Null  :=  " Input_SQLDA" ; 

Outpv  _SQLDA  ;  constant  SQL_Char_Not_Null  :=  "Output_SQLDA"  ; 

SQLTYPE  SQL_Dynamic  Datatypes;  —  type  declared  in  SQL_Dynamic_Pkg 

SQLD_Out,  SQLD_In  :  SQL_Int_Not_Null; 

Is_Fetched  :  boolean,  --  result  parameter  for  fetch 

begin 

—  assume  the  dynamic  statement  is  available  in  object  STMT, 

—  of  type  SQL_Char_Not_Null .  Assume  also  it  is  the  only  statement 

—  which  will  be  in  use  at  any  one  time.  This  allows  for  constant 

—  statement  identifiers  and  cursor  names . 

Prepare (STMT) ; 

—  a  failure  here  is  probably  a  badly  formed  statement .  This  can 
--  be  trapped  here,  using  an  SQLCODE  result  mapping  and  parameter. 
Allocate (SQLDA_Name  =>  Input  SQLDA,  Max  =>  Max_SQLVAR) ; 

Allocate ( S QLD A_N ame  =>  Output_SQLDA,  Max  =>  Max_SQLVAR) ; 

—  Failure  here  is  irrecoverable . 

Describe_In (Input_SQLDA) ;  —  Inputs  to  the  prepared  Statement 
Describe (Output  SQLDA) ;  —  Outputs .  The  statement  identifier 

—  is  statically  known  to  the  module . 

—  Failure  here  is  irrecoverable . 

Cet_SQLD  ( SQLDA_N ame  =>  Input_SQLDA,  SQLD  =>  SQLD_In)  ; 

—  Failure  here  is  irrecoverable, 
if  SQLD_In  >  0  then 

for  i  In  1  .  .  SQLD_In  loop 

Get_SQLTYPE (SQLVAR_Nbr  =>  i, 

SQLD A_N ame  =>  Input_SQLD A , 

SQLTYPE  =>  SQLTYPE) ; 

—  Failure  here  is  irrecoverable . 

case  SQLTYPE  is 

when  Dyn ami c_Cha r  => 

—  get  the  character  string  from  the  user. 

--  assume  it  is  in  an  object  called  Char_Obj  of  type 
—  SQL_Char_Type  in  SQL_Base_Types_Pkg. 
Set_SQLDATA(SQLVAR_Nbr  «=>  i, 

SQLDA_Name  =>  I nput_S QLDA , 

SQLDATA  =>  Char_0bj); 

—  Include  an  alternative 

—  for  each  element  of  SQL_Dynamic_Datatypes . 

—  The  object  containing  the  input  value  will  be  distinct 

—  in  each  alternative,  as  it  will  have  a  distinct  type. 

end  case; 
end  ioop; 
end  if; 

Get_SQLD  ( SQLD A_N ame  =>  Output_SQLDA,  SQLD  =>  SQLD_Out)  ; 
if  SQLD_ Out  =  0  then  —  if  no  outputs,  not  a  select 
Execute (SQLDA_Name  =>  Input_SQLDA) ; 

—  There  are  many  non  successful  statuses  which  might  be 

—  trapped  hers:  permission  or  constraint  violation, 

—  record  not  found,  etc.  This  is  omitted  here,  as  it  has  been 

—  fully  illustrated  elsewhere . 

else  --  if  it  does  have  outputs,  it  is  a  select 

—  cursor  does  not  need  to  be  declared,  as  both  cursor  name 

—  and  statement  identifier  are  statically  known  to  the  module 
Open_Cur«or ( SQLDA  Name  =>  Input_SQLDA) ; 

--  Failures  on  Open  are  irrecoverable. 
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F e tch ( SQLDA_N am*  =>  Output_SQLDA,  Result  =>  Is_Fetched) ; 
if  not  l«__F«tchad  then 

—  perform  'no  records  were  retrieved'  processing 

else 

while  Ia_Fetched  loop 

for  i  in  l  . .  SQLD_Out  loop 

Get_SQLTYPE (SQLVAR_Nbr  =>  i, 

SQLDA_Naroe  =>  Output  SQLDA, 

SQLTYPE  =>  SQL TYPE) ; 
case  SQLTYPE  is 

When  Dynami c_Char  => 

Get_SQLDATA(SQLVAR_Nbr  =>  i, 

SQLDA_Narae  =>  Input_SQLDA, 
SQLDATA  =>  Ch*r_Obj); 

—  process  Cbar_Obj  as  needed 
—  An  alternative  is  need-.-! 

--  for  for  each  type  in  SQL_Dynaroic_Datatypee . 

end  case,- 
end  loop; 

—  end  of  tuple  processing 

end  loop; 

—  end  of  file  processing 

end  if; 

--  end  of  cursor  processing 
Close_Cursor; 
end  If; 

—  end  of  statement  processing 

end  ; 

Figure  9-4:  Dynamic  SQL  Application  Fragments 


9.2.  SQL  and  Ada  Tasks 


This  section  delineates  issues  arising  from  the  use  of  SQL  within  an  Ada  application  using 
Ada  tasking.  The  issues  stem  from  both  practical  and  theoretical  aspects  of  concurrency 
control. 

The  tasks  within  an  Ada  multi-tasking  program  form  a  set  of  mutually  cooperating  sequential 
programs.  The  cooperation  is  mediated  by  shared  variables  and  rendezvous.  The  trans¬ 
actions  executing  concurrently  against  a  shared  database  form  a  set  of  mutually  non¬ 
interfering  sequential  programs.  The  non-interference  is  mediated  by  the  DBMS’s  concur¬ 
rency  control  protocol,  typically  locking.  The  difference  between  these  two  views  of  concur¬ 
rency  is  profound.  Whereas  the  purpose  of  an  Ada  task  control  monitor  is,  in  part,  to  ensure 
that  inter-task  communication  and  cooperation  proceed  smoothly,  the  purpose  of  a  DBMS 
concurrency  control  monitor  is  to  ensure  that  inter-transaction  communication  does  not  oc¬ 
cur  at  all.  The  difference  in  the  meaning  of  correctness  of  concurrent  execution  of  Ada  tasks 
and  DBMS  transactions  requires  that  Ada  multi-tasking  DBMS  applications  be  carefully  de¬ 
signed.  In  particular,  the  mapping  between  Ada  tasks  and  DBMS  transactions  must  be  care¬ 
fully  considered. 

A  task  is  said  to  be  directly  associated  with  a  transaction  if  the  task  executes  a  statement  of 
the  transaction,37  by  way  of  an  abstract  procedure  call.  A  task  is  indirectly  associated  with  a 
transaction  if  it  causes  the  execution  of  such  a  statement  within  a  task  that  is  directly  associ¬ 
ated  with  the  transaction.  (There  may  be  tasks  which  are  neither  directly  nor  indirectly  asso¬ 
ciated  with  any  transaction.)  A  mapping  between  tasks  and  transactions  is  a  relation  which 
gives  the  tasks  and  their  associated  transactions  at  some  point  during  the  execution  of  the 
program.  (An  application  may  terminate  and  restart  transactions  during  its  execution.  Such 
sequences  of  transactions  which  do  not  overlap  in  time  present  no  difficulties.  The  design 
and  coding  difficulties  arise  in  connection  with  sets  of  concurrent  transactions  associated 
with  a  single  Ada  program.)  This  mapping  can  be  of  one  of  four  classes. 

1.  One-to-one.  A  task  is  associated,  directly  or  indirectly,  with  at  most  one  trans¬ 
action;  a  transaction  is  associated  with  exactly  one  task. 

2.  Many-to-one.  A  task  is  associated  with  at  most  one  transaction;  a  transaction 
is  associated  with  any  (positive)  number  of  tasks. 

3.  One-to-many.  A  task  is  associated  with  any  number  of  transactions;  each 
transaction  is  associated  with  exactly  one  task. 

4.  Many-to-many.  The  mapping  between  tasks  and  transactions  is  uncon¬ 
strained. 

Since  a  DBMS  considers  a  transaction  to  be  a  sequential  program,  it  cannot  tolerate  concur¬ 
rent  execution  of  multiple  requests  on  behalf  of  a  single  transaction.38  In  other  words,  if 
either  of  the  relations  many-to-one  or  many-to-many  between  tasks  and  transactions  is  de¬ 
sired,  the  many  tasks  associated  with  any  transaction  must  all  use  a  synchronization  or  ser- 


37The  means  by  which  a  DBMS  identifies  the  transaction  on  behalf  of  which  a  statement  is  to  be  executed  is  a 
central  issue  which  will  be  discussed. 

38Th ere  are  research  DBMS  prototypes  which  allow  overlapped  execution  of  database  operations  within  the 
context  of  a  single  task.  It  is  highly  probable  that  no  commercially  available  DBMS  supports  such  processing. 
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vice  task  to  control  database  operations  for  that  transaction.  If  an  Ada  multi-tasking  pro¬ 
gram  is  to  appear  to  the  database  as  a  single  transaction  at  every  point  in  its  execution, 
provision  of  this  synchronization  task  is  all  that  is  required. 

The  synchronization  task  can  be  designed  so  as  to  contain  the  abstract  module(s)  for  all  of 
the  tasks  associated  with  the  synchronization  task’s  transaction.  This  may  well  be  a  poor 
design  choice,  in  particular,  it  may  give  rise  to  an  inordinate  number  of  task  entries.  Alter¬ 
natively,  each  task  within  the  transaction  may  contain  its  own  abstract  module.  The 
synchronization  task  provides  a  semaphore  service.  Calls  to  the  semaphore  task's  entries 
belong  in  the  application,  as  the  abstract  module  deals  only  with  database  interaction  and 
should  not  be  aware  of  task  structure.  The  semaphore  should  be  acquired  before  each  call 
to  the  abstract  module’s  procedures  and  released  upon  return.  This  will  ensure  that  the 
global  SQLCODE  variable  in  SQL_Communications_Pkg,  which  will  be  shared  by  the  tasks, 
is  accessed  in  the  critical  region  delineated  by  the  get  and  release  calls  to  the  semaphore. 

If  an  Ada  program  is  designed  to  present  multiple,  concurrent  transactions  to  the  DBMS, 
careful  consideration  must  be  given  to  the  semantics  of  this  situation.  For  simplicity,  assume 
exactly  two  tasks,  T1  and  T2,  each  associated  with  exactly  one  transaction,  N1  and  N2. 

The  DBMS  will  schedule  the  operations  of  N1  and  N2  such  that  they  are  serializable.  This  is 
to  say  that,  given  the  information  available  to  the  DBMS,  which  is  exactly  the  sequence  of 
DBMS  operations  within  N1  and  N2,  the  DBMS  will  schedule  those  operations  so  that  their 
net  effect  is  identical  to  the  effect  of  executing  one  of  those  sequences  in  its  entirety  fol¬ 
lowed  by  the  entirety  of  the  other  sequence.  In  short,  serializabilty  provides  to  each  DBMS 
transaction  the  illusion  that  it  is  running  by  itself,  without  competing,  concurrent  transactions. 
Now  suppose  that  T1  and  T2  share  information,  through  global  variables  or  rendezvous:  that 
the  information  they  share  is  derived  from  the  database  operations  they  execute;  and  that 
the  database  operations  they  execute  are  determined  by  the  information  they  share.  In  this 
case,  T1  and  T2  cannot  be  serialized;  their  net  effect  is  not  equivalent  to  their  complete, 
non-parallel  execution  in  any  order.  However,  that  fact  is  unknown  to  the  DBMS.  It  may  well 
be  that  this  scenario  is  not  erroneous.  That  will  depend  on  the  semantics  of  the  tasks’  inter¬ 
action.  But  it  must  be  carefully  reviewed. 

Cooperating  tasks  presenting  distinct  transactions  to  the  DBMS,  such  as  T1  and  T2  in  the 
prior  paragraph,  must  be  able  to  deal  with  each  other’s  abnormal  termination.  A  DBMS  may 
abnormally  terminate  a  well  formed,  semantically  correct  transaction  in  order  to  resolve  a 
detected  deadlock.  If,  for  example,  T2  has  given  information  derived  from  the  database  to 
T1,  and  its  associated  transaction,  N2,  is  abnormally  terminated  by  the  DBMS,  the  DBMS 
will  not  abnormally  terminate  N1 ,  since  it  does  not  know  that  the  communication  has  taken 
place.  T1  must  be  able  to  detect  that  situation  and  take  whatever  action  is  appropriate.39 

The  discussion  so  far  has  centered  on  the  theoretical  issues  involved  in  forming  seman¬ 
tically  correct  multi-tasking,  multi -transaction  Ada  DBMS  applications.  An  example  of  such  a 
well-formed  application  is  the  case  of  multiple  task  executions  of  the  same  task  type,  each 
execution  operating  on  behalf  of  a  distinct  user,  without  inter-task-object  communication. 

The  remainder  of  this  section  deals  with  the  practical  aspects  of  constructing  such  well- 
formed  applications. 


39This  situation  is  not  unique  to  DBMS  applications.  Any  set  of  cooperating  tasks  must  be  able  to  deal  with 
each  other's  abnormal  termination. 
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It  must  be  noted  immediately  that  neither  the  current  ANSI  standard  [2],  nor  the  follow-on 
standard  [3],  allow  for  the  construction  of  multi-transaction  programs.  This  is  because  there 
is  no  way  in  the  standard  to  associate  a  statement  execution  with  a  particular  transaction 
among  a  concurrent  set  of  transactions.  This  topic  will  be  addressed  below. 

The  ability  to  construct  multi-transaction  Ada  programs  depends  in  large  measure  on  the 
target  DBMS.  There  are  many  things  to  consider.  Every  Ada  DBMS  application  will  contain 
in  its  executable  image  some  code  supplied  by  the  DBMS.  This  code  will  be  called  the 
DBMS  stub.  The  function  of  this  stub  is  to  accept  the  DBMS  call  from  the  concrete  module 
and  transfer  control  to  the  DBMS,  which,  in  a  multi-user  operating  environment,  may  be  ex¬ 
ecuting  as  a  separate  process,  in  a  separate  address  space,  or  even  on  a  separate  ma¬ 
chine.  It  must  be  the  case  that  either  this  stub  code  is  reentrant,  that  is,  capable  of  executing 
multiple,  parallel  threads  of  control,  or  that  each  task  associated  with  each  transaction  has 
its  own,  private  copy  of  that  code.  If  neither  of  these  things  can  be  done,  multi-transaction 
programs  cannot  be  written.  The  same  reasoning  holds  for  the  concrete  module,  if  distinct 
tasks,  directly  associated  with  distinct  transactions,  are  to  share  an  abstract,  and  therefore 
also  a  concrete,  module. 

If  the  reentrancy  requirements  of  the  previous  paragraph  are  met  by  the  target  DBMS,  the 
final  obstacle  is  the  means  by  which  the  DBMS  identifies  the  transaction  on  whose  behalf  a 
given  statement  is  to  be  executed.  In  the  case  of  a  single  user  DBMS,  as  might  be  found  on 
a  PC  class  machine,  all  statement  executions  are  part  of  the  same  transaction,  and  multi¬ 
transaction  programs  cannot  be  written.  If  a  multi-user  DBMS  identifies  transactions  on  the 
basis  of  the  identity  of  the  program  executing  the  statement,  using  operating  system  fea¬ 
tures  to  make  that  identification,  multi-transaction  programs  are  again  impossible.  If  the 
DBMS  identifies  the  transaction  by  some  parameter  of  the  call  itself,  such  as  the  address  of 
a  "communication  area,”  then  this  parameter  can  be  called  a  transaction  identifier.  Trans¬ 
action  identifiers  do  not  appear  in  SQL  statements.  Dynamic  modification  of  that  parameter 
requires  understanding  of,  and  possibly  modification  to,  the  code  generated  by  an  SQL 
preprocessor  or  concrete  module  compiler,  particularly  in  the  case  where  that  concrete  mod¬ 
ule  code  is  to  be  shared  by  task  objects.  This  is  a  tricky  and  dangerous  business,  which  can 
result  in  engineering  nightmares.40 

One  way  to  ensure  that  task  objects  do  not  share  abstract  or  concrete  modules  is  to  place 
these  modules  within  the  bodies  of  the  tasks.  If  the  task  objects  are  to  logically  (but  not 
physically)  share  an  abstract  module,  the  module  can  be  made  into  a  parameterless  generic 
which  is  instantiated  into  the  task  body.  If  the  DBMS  identifies  transactions  via  a  transaction 
identifier  generated  by  the  SQL  processor,  this  solution  may  work,  at  the  expense  of  in¬ 
creased  object  code  size  on  most  compilers.  This  solution  will  probably  not  work  to  solve 
reentrancy  problems  for  the  DBMS  stub  code  referenced  earlier.  That  code  is  usually 
brought  into  the  executable  by  the  system  linker,  which  normally  resolves  references  by 
name,  thereby  sharing  one  copy  of  the  stub  among  all  the  tasks. 

If  multi-transaction  programs  are  not  prohibited  by  any  of  these  considerations,  then  such 
programs  can  be  written  if  a  minor  modification  is  made  to  the  standard  SAME  support 
packages.  In  particular,  the  package  SQL_Communications_Pkg  presents  a  difficulty  as  it 
exports  a  global  variable,  SQLCODE.  This  variable  can  be  made  local  to  a  task  object  by 


40lt  may  be  that  a  DBMS  extends  SQL  to  provide  a  transaction  identifier.  The  author  knows  of  no  such  DBMS 
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the  method  of  the  prior  paragraph,  i.e.,  by  placing  this  package,  along  with  the  abstract  and 
concrete  modules  and  the  package  SQL_Database_Error_Pkg,  into  the  body  of  the  tasks.  If 
that  is  otherwise  not  necessary  or  desirable,  then  the  package  SQL_Communication_Pkg 
and  the  calling  conventions  at  the  abstract  module  level  (and  the  concrete  level  as  well,  in  a 
non-standard  way,  see  the  previous  discussion),  can  be  modified  as  follows:  Remove  the 
variable  SQLCODE  from  the  specification  of  SQL_Communications_Pkg  and  replace  it  with 
the  following  type  definition: 

type  Tr*n«action_Id_Typ«  is  record 
SQLCODE  :  SQLCODE_Typ« ; 

<unpl«XD*rrtati.on  d«p«ndant  private  record  typa> 

end  record; 

(The  implementation-dependent  portion  of  the  type  Transaction_ld_Type  is  meant  to  accom¬ 
modate  an  implementation  defined  “communications  area.”  Such  an  object  may  also  be 
added  to  the  definition  of  SQL_Communications_Pkg  in  the  single  transaction  case.)  Each 
task  object  directly  associated  with  a  transaction  must  allocate  an  object  of  this  type  in  a 
manner  which  will  allow  it  to  persist  across  all  abstract  module  procedure  calls.  The 
parameter  lists  of  such  calls  are  extended  to  include  that  object,  which  is  a  transaction  iden¬ 
tifier.  The  procedure  Process_Database_Error  in  SQL_Database_Error_Pkg  is  also 
amended  to  include  this  parameter.  Any  handler  for  for  the  SQL_Database_Error  exception 
must  be  able  to  find  the  appropriate  transaction  identifier. 
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A  SAME  Quick  Reference  List 


A.1  Example  Domains 

Let  Dom  be  an  abstract  domain  name  for  the  SQL  <type>  domains  for  int, 
smallint,  real,  and  double_precision. 


With  SQL_<typ«>_Pkg;  Use  SQL_<typ«>_Pkg; 

type  Dom_Not_Null  is  new  SQL_<typ«>_Not_Null; 
type  DomjCypm  is  new  SQL_<typ«>; 

package  Dom _Crpm  is  new  SQL_<typ«>_Op«  (Oom_Type,  Dom_Not_Hull)  ; 


Let  Dom  be  an  abstract  domain  name  for  the  SQL  Character  domain.  In  the  following 
example,  n  represents  the  number  of  characters  in  the_Not_Null  portion  of  the 
domain. 

With  SQL_Char_Pkg;  use  SQL_Char_Pkg; 

type  DomNN_Ba««  is  new  SQL_Char_Not_Null; 
subtype  Dom_Not_Null  is  DomNN_Ba»«  (1 . .  n)  ; 
type  Do/77_b**«  is  new  SQL_ch*r; 

subtype  DomJType  is  Dom_B*mm  (Doro_Not_Null'  Length)  ; 

package  Dom_ Op«  is  new  S<2L_Cbar_0^«  ( Dom_Typ« ,  Dom_Not_Null)  ; 


Let  Dom  be  an  abstract  domain  name  for  an  SQL  enumeration  domain. 


With  SQL_Enumaration_P  kg ; 

type  Dom_Not_Null  is  ( literal,  literal,  . . . ,  literal) ; 

package  Dom_ Pkg  Is  new  SQL_Enumaration  Pkg  (Dom_ Not_Null)  ; 

type  Dom_Typ*  is  new  Dorn_P  kg .  SQL^Enun*®  ration; 

Let  Dom  be  an  abstract  domain  name  for  an  SQL  Decimal  domain.  Let 
the  scale  of  the  domain  be  s. 


With  SQL_D*cimal_Pkg,  Ad*_BCD_Pkg; 

Use  SQL_Decimal__Pkg,  Ada_BCD_Pkg; 

Dom_ Seal*  :  constant  dacimal_digit«  :=  s; 
type  DomHN_Baa«  is  new  SQL_D«cimal_Not_Null; 
subtype  Oom_Not_Null  is  DomNN_B*««  (scale  =>  Dom_ Scale); 
type  Dom_B*m%  is  new  SQL_cliar; 

subtype  Dom_Typ*  is  Dom_Baae  (scale  =>  Dom_ Scale) ; 
package  Dom _Opm  is  new  SQL_char_Ops(Dom_Type, 

in_scale  =>  Dom  Scale)  ; 


See  Chapter  3  for  further  details. 
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A.2  Functions  Available  to  the  Application 

Operand  Type 

Left  Right  Result 


All  Domains 


i  jll_3QL_<type> 

.Type 

With_Null 

_Not_Null 

.Type 

Without_Null 

.Type1 

.Not.Null2 

Is_Null,  Not_Null 

.Type 

Boolean 

Assign3 

_Type 

.Type 

Equals,  Not_Equals 

_Type 

.Type 

B.W.U4 

<,  >,  <=,  >= 

_Type 

.Type 

B.W.U 

=  ,  /=,  >,  <,  >=-  <= 

_Type 

.Type 

Boolean 

Numeric  Domains 

unary  +,  -,  Abs 

.Type 

.Type 

+  /  ~t  ! ,  * 

_Type 

.Type 

.Type 

** 

_Type 

Integer 

.Type 

Int  and  Smallint  Domains 

Mod,  Rem 

Type 

.Type 

.Type 

Image 

Type 

SQL  Char 

Image 

_Not_Null 

SQL.ChrNN5 

Value 

SQL_Char 

.Type 

Value 

SQL_ChrNN 

.Not.Null 

Decimal  Domains 

=,  /=,  >,  <,  >=,  <= 

_Not_Null 

.Not  Null 

Boolean 

unary  +,  -,  abs 

.Not  Null 

.Not.Null 

+  /  ~r  *  /  / 

_Not_Null 

.Not  Null 

Not.Null 

*,  /6 

_Not_Null 

SQL.IntNN 

.Not.Null 

*,  / 

_Type 

SQL.IntNN 

.Type 

*,  / 

_Type 

SQL.Int 

.Type 

* 

SQL_IntNN 

.Not  Null 

Not.Null 

■k 

SQL_IntNN 

_TYPe 

.Type 

* 

SQL_Int 

.Type 

.Type 

Zero,  One 

.Not.Null 

Zero,  One 

.Type 

Assign3 

_Not_Null 

.Not  Null 

Shift 

Not_Null 

Integer 

.Not.Null 

Shift 

Type 

Integer 

.Type 

Width 

_Not_Null 

Integer 

Width 

Type 

Integer 

Fore,  Aft 

_Not_Null 

Integer 

Fore,  Aft 

Type 

Integer 

Integral,  Scale 

_Not_Null 

Integer 

Integral,  Scale 

_Type 

Integer 

Is_In 

_Not_Null 

Boolean 

Is_In 

_Type 

Boolean 

Exceptions 


Nul  l.Va lue_E rror 
Constraint  Error 


Constraint_Error 
Constraint_Error 
Constraint_Error 
Constraint_Error 
Constraint_Error 
Constraint_Error 
Constraint  Error 


Const raint_Error 
Const raint_Error 
Const raint_Error 

Null.Value.Error 

Niill.Value.Error 

Null  Value  Error 
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Operand  Type 


Left 

Right 

Result 

Decimal  Domains  (cont.) 

Machine  Rounds 

_Not_Null 

Boolean 

Machine_Rounds 

_ Type 

Boolean 

Machine  Overflows 

_Not_Null 

Boolean 

Machine  Overflows 

Type 

Boolean 

To  SQL  Decimal_Not_Null 

SQL_IntNN 

_Not_Null 

To  SQL  Decimal_Not_Null7 

SQL_DblNN 

_Not_Null 

To  SQL_Decimal_Not_Null 

SQL_ChrNN 

_Not_Null 

To  SQL  Decimal 

SQL_IntNN 

_Type 

To_SQL_Decimal 

SQL_Int 

Type 

To  SQL_Decimal 

SQL_DblNN 

_Type 

To_SQL_Decimal8 

SQL_Dbl 

_Type 

To  SQL  Decimal 

SQL_ChrNN 

_Type 

To  SQL  Decimal 

SQL_Char 

_Type 

To  SQL  Int_Not_Null 

_Not_Null 

SQL_IntNN 

To  SQL _ Int_Not_Null 

_ Type 

SQL_IntNN 

To_SQL_Int 

_Type 

SQL_Int 

To  SQL  Double  Precision_Not  Null 

_Not_Null 

SQL_DblNN 

To  SQL  Double  Precis ion_Not  Null 

_Type 

SQL_DblNN 

To  SQL  Double_Precision 

_Type 

SQL_Dbl 

To  SQL_Char  Not_Null 

_Not_Null 

SQL_ChrNN 

To  SQL_Char  Not_Null 

_ Type 

SQL_ChrNN 

To  SQL  Char 

_Type 

SQL_Char 

To_String 

_Not_Null 

String 

To_String 

_Type 

String 

Character  Domains 

Without_Null_TJnpadded 

_Type 

_Not_Null 

To_String 

_Not_Null 

String 

To_String 

_Type 

String 

To_Unpadded_String 

0 

H 

H 

String 

To_CJnpadded_String 

_Type 

String 

To_SQL_Char_Not_Null 

String 

_Not_Null 

T  o_S  Q  L_Ch  a  r 

String 

JType 

Unpadded_Length 

_Type 

SQL_U_L9 

Substring10 

_Type 

_Type 

&  _Type 

_Type 

_Type 

Enumeration  Domains 

Pred,  Succ 

_Type 

_Type 

Image 

_Type 

SQL_Char 

Image 

_Not_Null 

SQL_ChrNN 

P03 

_Type 

Integer 

Val 

Integer 

_Type 

Value 

SQl_Char 

_Type 

Value 

SQL  ChrNN 

_Not_Null 

Exceptions 


Const raint_Error 
Constraint  Error 


Constraint_Error 
Const raint_Error 
Const raint_Error 
Const raint_Error 
Constraint_Error 
Constraint_Error 
Nuil__Value_Error 
Const raint_Error 

Null  Value  Error 


Null  Value  Error 


Null  Value  Error 


Null_Value_Error 
Null_Value_Error 
Null  Value  Error 


Null_Value_Error 
Constraint  Error 


Null  Value  Error 
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Exceptions 


Operand  Type 


Left 

Boolean  Functions 


not 

and,  or,  xor 

B_W_U 

To_Boolean 

Is  True,  B  W_U 


Is  False, 

B_W_U 

Is  Unknown 

B  W  U 

Right  Result 


B_W_U  Boolean 

B_W_U  Boolean 

B_W_U  Boolean  Null_Value_Error 

B_W_U  Boolean 

B_W_U  Boolean 

B  W  U  Boolean 


1.  "_Type"  represents  the  type  in  the  abstract  domain  of  which 

objects  that  may  be  null  are  declared. 

2.  "_Not_Null"  represents  the  type  in  the  abstract  domain  of  which 

objects  that  are  not  null  may  be  declared. 

3.  "Assign"  is  a  procedure.  The  result  is  returned  in  object 

"Left. " 

4.  "B_W_U"  is  an  abbreviation  for  Boolean_With_Unknown . 

5.  "SQL_ChrNN"  is  an  abbreviation  for  SQL__Char_Not_Null . 

6.  "SQL_IntNN"  is  an  abbreviation  for  SQL_Int_Not_Null . 

7.  "SQL_DblNN"  is  an  abbreviation  for 

SQL_Double_Precision_Not_Null . 

8.  "SQL_Dbl"  is  an  abbreviation ' for  SQL_Double_Precision . 

9.  "SQL_U_L"  is  an  abbreviation  for  the  SQL_Char_Pkg  subtype 

SQL_Unpadded_Length . 

10.  Substring  has  two  additional  parameters:  Start  and  Length, 

which  are  both. of  the  SQL_Char_Pkg  subtype 
SQL_Char_Length .  ' 
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B  Glossary  of  Terms 

Abstract  domain.  A  real  world  collection  of  values.  Differs  from  both  an  Ada  type  and  an 
SQL  type  in  that  it  is  a  real  world  object,  not  a  programming  object.  An  abstract  domain  is 
represented  in  an  Ada  program  by  a  pair  of  type  definitions  and  a  generic  package  instan¬ 
tiation.  One  of  the  types,  the  _Not_Null  type,  can  represent  any  value  in  the  abstract  domain 
except  the  null  value.  The  other  type,  the  _Type,  can  represent  the  null  value  as  well.  The 
two  types  are  syntactically  connected  through  the  convention  of  having  the  same  prefix. 

That  is,  the  abstract  domain  Domain  is  represented  by  the  two  Ada  types  Domain_Not_Null 
and  Domain  _ Type.  The  two  types  are  semantically  connected  through  the  instantiation  of 
an  _Ops  package.  See  _Not_Null  type,  _Type  type,  _Ops  package,  and  Visible  Ada  type. 

Abstract  Interface.  The  specification  of  the  abstract  module.  Contains  the  declarations  of 
row  record  types  and  of  abstract  procedures.  See  Abstract  module,  Abstract  procedure, 
Row  record  type. 

Abstract  module.  The  body  of  the  abstract  interface.  Contains  the  bodies  of  the  abstract 
procedures.  See  Abstract  interface  and  Abstract  procedure. 

Abstract  procedure.  The  procedure  called  by  the  application  program  to  perform  database 
interaction.  The  abstract  procedure  calls  the  concrete  procedure  to  perform  the  interaction. 
The  abstract  procedure  does  error  checking  by  examining  the  SQLCODE  variable  and  takes 
action  as  necessary.  It  also  does  data  conversion  from  concrete  to  abstract  types.  See 
Abstract  interface,  Abstract  module,  Concrete  procedure,  SQLCODE,  and  Standard  error 
processing. 

Ada  semantics.  Refers  to  the  operations  predefined  in  Ada  for  arithmetic,  comparison,  etc. 

Ada  typing  model.  The  ability,  in  Ada,  for  the  programmer  to  define  new  types  from  exist¬ 
ing  types.  The  phrase  also  refers  to  Ada's  use  of  name  equivalence,  rather  than  structural 
equivalence,  to  determine  object  typing.  As  two  integer  types  with  the  same  integer  range 
constraint  being  nonetheless  distinct.  Ada's  typing  model  also  includes  so-called  “strong” 
typing. 

Application  program.  The  part  of  the  complete  application  which  contains  that  part  of  the 
application  logic  that  is  written  in  Ada.  It  contains  none  of  the  application  logic  written  in 
SQL,  nor  any  of  the  bookkeeping  logic  for  executing  the  SQL.  See  Concrete  module  and 
Abstract  module. 

Attribute.  See  Column. 

_Base  type.  Within  the  definition  of  a  string-based  abstract  domain,  the  unconstrained 
types.  The  _Not_Null  and  _Type  types  are  subtypes  of  the  _Base  types.  See  SQL  String 
processing,  _Not_Null  type,  and  _Type  type. 

Column.  A  field  of  a  row  within  a  table.  Corresponds  to  Ada's  scalar  variable  in  that  a  field 
must  hold  an  atomic  value  and  may  not  contain  a  composite  value.  (Character  strings  are 
thought  of  as  atomic  in  this  sense.) 
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Concrete  interface.  Specification  of  the  concrete  module.  Contains  the  declarations  of  the 
concrete  procedures.  See  Concrete  module  and  Concrete  procedure. 

Concrete  module.  Contains  the  bodies  of  the  concrete  procedures.  See  Concrete  inter¬ 
face  and  Concrete  procedure. 

Concrete  procedure.  A  procedure  in  the  concrete  module.  Concrete  procedures  perform 
database  interaction.  Each  concrete  procedure  corresponds  to  a  single  SQL  statement. 

Concrete  types.  The  types  defined  in  SQL_Standard.  These  types  describe  the  represen¬ 
tation  of  data  in  the  database. 

Comparison  rule.  A  heuristic  for  determining  if  two  values,  variables,  or  columns  have  the 
same  type  or  abstract  domain.  The  rule:  If  it  makes  sense  to  compare  the  values,  variables 
or  columns,  then  they  have  the  same  type  or  abstract  domain.  If  it  makes  no  sense  to  com¬ 
pare  them,  then  they  have  different  types  or  domains. 

Cursor.  Used  by  SQL  to  communicate  with  application  languages.  A  cursor  is  associated 
with  a  Select.. .From. ..Where  block.  A  cursor  may  be  opened,  fetched,  and  closed.  See  an 
SQL  description  (e.g.,  Database  Language  -  SQL  [2])  for  details.  A  cursor  is  a  quasi-object 
in  that  it  can  be  updated  and  it  has  state,  but  it  is  not  available  for  any  programming  opera¬ 
tions  other  than  SQL  statements.  The  state  of  a  cursor  is  closed  or  open;  an  open  cursor 
records  a  current  position  (row)  within  the  associated  table.  The  current  row  may  be  deleted 
or  updated. 

Database  exceptional  condition.  Any  condition  which  causes  SQLCODE  to  be  set  to  a 
non-zero  value  upon  return  from  a  concrete  procedure.  Includes  “no  record  found.”  Excep¬ 
tional  conditions  may  be  expected  or  unexpected.  See  Result  parameter  and  Standard  error 
processing. 

Data  integrity  constraints.  Statements  made  about  the  contents  of  the  database  that  are 
enforced  by  the  database  management  system. 

Data  semantics.  The  meaning  of  the  operations  defined  on  a  set  of  values.  See  Ada 
semantics  and  SQL  semantics. 

Derived  type.  A  type  whose  operations  and  values  are  replicas  of  those  of  an  existing  type. 
The  existing  type  is  called  the  parent  type  of  the  derived  type.  LRM  glossary  [15]. 

Domain  package.  An  Ada  package  specification  containing  only  declarations  of  abstract 
domains.  No  abstract  domain  declaration  may  appear  in  more  than  one  domain  package, 
and  no  abstract  domain  declaration  may  appear  outside  of  a  domain  package.  See  Abstract 
domain. 

Dynamic  SQL.  A  form  of  SQL  in  which  the  statement  to  be  executed  is  created  by  the 
application  at  run  time.  Dynamic  SQL  is  used  when  a  database  interaction  takes  parameters 
which  are  not  constants.  These  can  be  search  conditions,  table  names,  etc. 

Full  SQL  treatment  of  nulls.  The  discipline  of  handling  null  values  in  Ada  programs  that 
use  SQL  semantics  for  arithmetic  and  comparison  operators.  This  discipline  treats  variables 
_"fype  typo  as  regular  variables,  using  the  versions  of  arithmetic  and  comparison 
operators  exported  by  the  SAME  standard  packages. 
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Indicator  parameters.  Special  integer-typed  parameters  used  at  the  concrete  interlace  to 
record  information  about  other  parameters.  A  negative  indicator  parameter  value  indicates  a 
null  value  in  the  associated  parameter.  Indicator  parameters  do  not  appear  at  the  abstract 
interface. 

Minimalist  treatment  of  nulls.  The  discipline  for  handling  null  values  in  an  Ada  program 
that  uses  only  test  (ls_Null,  Not_Null)  and  conversion  (With_Null,  Without_Null)  functions. 
Treats  variables  of  _Type  type  as  value  repositories  only.  See  _Type  type,  Full  SQL  treat¬ 
ment  of  nulls. 

Modular  approach.  Any  technique  for  constructing  DBMS  application  software  which  phys¬ 
ically  separates  the  database  interaction  statements  and  the  programming  language  state¬ 
ments. 

Module.  A  related  set  of  procedures  which  perform  database  interaction.  See  Abstract 
Module,  and  Concrete  Module. 

Module  Language.  The  language  in  which  SQL  modules  are  written.  Part  of  ANSI  stan¬ 
dard  SQL.  The  module  language  describes  procedures,  the  bodies  of  which  are  single  SQL 
statements. 

_Not_Null  type.  One  of  the  two  types  making  up  an  abstract  domain  definition;  so-called 
because  the  set  of  objects  of  this  type  does  not  include  the  null  value.  Usually,  the 
_Not_Null  type  is  a  visible  Ada  type.  See  Abstract  domain  and  Visible  Ada  type. 

Null  value.  SQL’s  means  of  recording  missing  information.  A  null  value  in  a  column  in¬ 
dicates  that  nothing  is  known  about  the  value  which  should  occupy  the  column. 

__Ops  generic  package.  Each  of  the  SAME  standard  packages  contains  a  generic  sub¬ 
package  which  generates,  by  package  instantiation,  those  functions  or  procedures  that  can¬ 
not  be  produced  by  subprogram  derivation.  The  subpackage  name  is  formed  by  replacing 
the  _Pkg  suffix  in  the  containing  package  name  with  _Ops.  In  use,  the  _Ops  package  takes 
two  types  as  formal  parameters,  the  _Type  and  _Not_Null  types,  which  together  make  up 
the  abstract  domain  definition. 

Platform,  or  platform  specific.  The  platform  on  which  a  piece  of  software  runs  is  the  com¬ 
bination  of  the  hardware,  operating  system,  DBMS  and  Ada  compiler.  Pieces  of  the  SAME 
which  are  platform  specific  are  the  database  layer,  containing  the  packages  SQL_System 
and  SQL_Standard,  to  describe  concrete  DBMS  types  in  Ada,  SQL_Communications_Pkg, 
for  retrieving  and  storing  status  information  from  the  DBMS,  and  SQL_Database_Error_Pkg, 
for  reporting  errors. 

Result  parameter.  An  optional  parameter,  of  an  enumeration  type,  frequently  Boolean,  to 
every  abstract  procedure  declaration.  If  present,  the  result  parameter  is  used  by  an  abstract 
procedure  to  signal  the  occurrence  of  an  expected  exceptional  condition.  See  DBMS  excep¬ 
tional  condition. 

Row.  An  element  of  a  table.  Also  called  a  tuple.  Analogous  to  a  record  object.  See  Column 
and  Table. 
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Row  record.  The  object  returned  from  an  abstract  procedure  which  retrieves  data  from  the 
database.  Also,  the  object  given  to  an  abstract  procedure  which  stores  data  in  the  database. 
A  row  record  contains  a  field  for  each  element  in  the  target  list  of  the  SQL  statement  ex¬ 
ecuted  by  the  abstract  procedure. 

Row  record  type.  The  Ada  type  definition  of  the  row  record.  Declared  in  the  abstract  inter¬ 
face. 

SAME  standard  packages.  The  packages  which  support  the  SAME  method;  particularly, 
those  packages  which  support  SQL  data  semantics.  Those  packages  are  SQL_lnt_Pkg, 
SQL_Smallint_Pkg,  SQL_Real_Pkg,  SQL_Double_Precision_Pkg,  and  SQL_Char_Pkg, 
which  provide  support  for  the  standard  SQL  data  types.  Other  standard  SAME  packages  are 
SQL_System,  SQL_Standard,  SQL_Exceptions,  SQL_Boo!ean_Pkg, 
SQL_Communications_Pkg,  and  SQL_Database_Error_Pkg.  See  Platform,  SQL  semantics, 
Standard  error  processing,  and  User-defined  semantics. 

SQLCODE.  The  name  of  the  parameter  to  a  concrete  procedure  which  holds  the  status 
code  at  procedure  termination.  Also  references  the  values  of  the  parameter. 

SQL  module.  A  concrete  module  written  in  the  module  language. 

SQL  procedure.  A  procedure  defined  within  the  concrete  module  whose  semantics  are 
given  by  an  SQL  statement.  See  Concrete  module,  Module  language,  and  SQL  module. 

SQL  semantics.  The  operations  of  arithmetic  and  comparison  extended  to  cover  the  null 
value.  Refers  also  to  SQL  string  processing,  in  which  strings  are  automatically  padded  or 
truncated  during  comparisons  and  assignments.  See  Three-valued  logic  and  Three-valued 
arithmetic. 

SQL  String  Processing.  SQL  treats  character  strings  as  fixed  length  objects  in  some  cir¬ 
cumstances  and  varible  length  objects  in  others.  For  example,  all  string  objects  within  a 
given  database  column  have  the  same  length  which  is  given  by  the  column  definition.  How¬ 
ever,  when  transporting  data  between  and  application  and  the  database,  an  SQL  DBMS  will 
truncate  or  blank  pad  a  string  value,  as  appropriate  to  the  length  of  the  programming  lan¬ 
guage  variable.  When  comparing  strings  of  different  lengths,  SQL  pads  the  shorter  string 
with  blanks  before  the  compare.  The  SAME  standard  support  package  SQL_Char_Pkg  of¬ 
fers  an  Ada  implementation  of  these  semantics.  See  _Base  type,  _Type  type,  _Not_Null 
type. 

Standard  error  processing.  The  process  initiated  after  an  unexpected  exceptional  con¬ 
dition  arises:  Process_Database_Error  in  package  SQL_Database_Error_Pkg  is  called  and 
an  exception,  SQL_Database_Error,  defined  in  SQL_Communications_Pkg,  is  raised. 

Status  parameter.  See  Resuit  parameter. 

Three-valued  arithmetic.  The  arithmetic  operations  within  SQL  which  are  defined  to  cover 
the  null  value.  Three-valued  arithmetic  operations  act  just  like  their  normal  counterparts  on 
non-null  values;  they  return  the  null  value  if  any  of  their  operands  are  null. 
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Three-valued  logic.  The  extension  of  comparison  and  Boolean  operations  within  SQL  to 
cover  null  values.  SQL  comparison  operations  return  the  truth  value  UNKNOWN  if  either  of 
their  operands  are  null.  SQL  defines  Boolean  operations  (and,  or,  not)  on  the  three-valued 
set  of  Boolean  operands  [FALSE,  UNKNOWN,  TRUE], 

Transaction.  A  logic  unit  of  database  work.  Database  transaction  control  provides 
transaction  atomicity;  i.  e.,  (1)  either  all  of  the  database  modifications  performed  by  any 
transaction  occur  or  none  of  them  do,  and  (2)  the  effect  of  every  successful  transaction  is 
the  same,  whether  or  not  other  transactions  are  executing  concurrently. 

_Type  type.  One  of  the  two  types  making  up  an  abstract  domain  definition.  The  set  of 
objects  of  this  type  includes  the  null  vaiue.  Usually,  the  _Type  type  is  a  private  record  type. 
See  Abstract  domain. 

User-defined  semantics.  The  semantics  of  operators  supplied  by  support  packages  writ¬ 
ten  by  users.  These  packages  allow  users  to  the  SAME  to  fit  local  needs. 

Visible  Ada  type.  Opposite  of  a  private  type.  See  _Not_Nu!l  type. 
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C  SAME  Standard  Package  Listings 


C.1  Introduction 

This  appendix  contains  the  source  code’  of  the  SAME  standard  packages.  This  code  will  be 
available  in  machine-readable  form  from  the  SEI  for  a  limited  time.  Please  read  the 
copyright  notice  in  the  next  section.  A  copy  of  this  notice  appears  in  each  file  of  the 
machine-readable  distribution. 

Every  procedure  and  function  declaration  in  these  packages  is  followed  by  a  pragma  IN¬ 
LINE  which  has  been  “commented  out."  The  explanation  for  this  is  as  follows.  Almost  all  of 
the  procedures  and  functions  in  these  packages  are  extremely  small.  Many  consist  of  a 
single  If  or  return  statement.  Therefore  they  are  excellent  candidates  for  procedure  inlining 
which  will  decrease  their  runtime  cost  by  the  overhead  of  a  procedure  call.  Experience  in 
using  this  code  with  various  compilers  has  shown  that  this  degree  of  inlining  tends  to  uncov¬ 
er  compiler  errors  and  produce  inexplicable  timings.  The  safest  approach,  that  of  not  using 
inlining  at  all,  has  be  chosen  for  the  code  as  distributed.  The  installer  is  urged  to  experiment 
with  the  iniining  of  this  code.  Some  experiments  have  shown  a  tenfold  speedup  due  to  inlin¬ 
ing  (whereas  other  experiments,  on  other  compilers  and  machine  architectures,  showed 
marginal  slowdown  due  to  inlining).  Recall  that  inlining  will  usually  make  the  resulting  object 
module  larger. 
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C.2  Copyright  Notice 

—  The  following  copyright  must  be  Included  In  this  softwscs  and 
—  all  software  utilizing  this  software. 


—  Copyright  (C)  1988  by  the  Carnegie  Mellon  University,  Pittsburgh,  PA. 

—  The  Software  Engineering  Institute  (SEI)  Is  a  federally  funded 

—  research  and  development  center  established  and  operated  by  Carnegie 

—  Mellon  University  (CMU) .  Sponsored  by  the  U.S.  Department  of  Defense 

—  under  contract  F19628-85-C-0003 ,  the  SEI  Is  supported  by  the 

—  services  and  defense  agencies,  with  the  U.S.  Air  Force  as  the 

—  executive  contracting  agent. 

—  Permission  to  use,  copy,  modify,  or  distribute  this  software  and  Its 

—  documentation  for  any  purpose  and  without  fee 

—  Is  hereby  granted,  provided 

—  that  the  above  copyright  notice  appear  In  all  copies  and  that  both 

—  that  copyright  notice  and  this  permission  notice  appear  In  supporting 

—  documentation.  Further,  the  names  Software  Engineering  Institute  or 

—  Carnegie  Mellon  University  may  not  be  used  In  advertising  or  publicity 

—  pertaining  to  distribution  of  the  software  without  specific,  written 

—  prior  permission.  CMU  makes  no  claims  or  representations 

—  about  the  suitability  of 

—  this  software  for  any  purpose.  This  software  is  provided  "as  is” 

—  and  no  warranty,  express  or  implied,  is  made  by  the  SEI  or  CMU, 

—  as  to  the  accuracy 

—  and  functioning  of  the  program  and  related  program  material,  nor 

—  shall  the  fact  of  distribution  constitute  any  such  warranty.  No 

—  responsibility  is  assumed  by  the  SEI  or  CMU  in  connection  herewith. 


C.3  SQL  System  Specification 


—  SQL_System  is  a  "platform-specific”  package 

—  within  the  SAME 

package  SQL_System  is 

—  MAXCHRLEN  is  the  length  of  the  longest  character  string 

—  which  the  DBMS  will  store . 

—  It  serves  as  the  upper  bound  on  SQL_Char_Pkg 

—  subtypes  SQL_Char_Length  and  SQL_Unpadded_Length. 

—  SQL_Char_Length  is  a  subtype  of  Natural  with  a  lower  bound 
of  1. 

—  SQL_Unpadded_Lenath  is  a  subtype  of  Natural  with  a  lower 

—  bound  of  0 . 

MAXCHRLEN  :  constant  Integer  :  *=  str  length;  —  replace 

—  MAXERRLEN  is  the  maximum  length  of  the  error  message 

—  string  returned  from  DBMS  specific  error  message  routine 

MAXERRLEN  :  constant  Integer  : =  msg_length;  --  replace 
end  SQL  System; 
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C.4  SQL_Standard  Specification 

package  Sql_Stendard  ie 

package  Character_Set  renames  cap; 
subtype  Character_Type  is  Character_Set . cat; 
type  Char  is  array  (positive  range  <>) 
of  Charactar_Type ; 
type  Smallint  is  range  bs..ts; 
type  Int  is  range  bi . . ti ; 
type  Real  is  digits  dr; 
type  Double_Precision  is  digits  dd; 

—  type  Decimal  is  to  be  determined; 
type  Sqlcoda_Type  is  range  bsc. . tsc; 
subtype  Sql  Error  is  Sqlcode  Type 

range  Sqlcode_Type ' FIRST  ..  -1; 
subtype  Mot_Found  is  Sqlcode  Type 
range  100.. 100; 
subtype  Xndicator_Type  is  t; 

—  cap  is  an  implementor-defined  package  and  cst  is  an 
implementor-defined  character  type,  be,  ts,  bi,  ti,  dr,  dd,  bsc, 
and  tsc  are  implementor  defined  integral  values,  t  is  int  or 
smallint  corresponding  to  an  implementor-defined  <exact 

—  numeric  type>  of  indicator  parameters . 

end  sql_standard; 


C.5  SQL  Communications  Pkg  Specification 

with  SQL_Char_Pkg;  use  SQL_Char_Pkg; 
with  SQL_Standard;  use  SQL_Standard; 
package  SQL_Communications_Pkg  is 

—  This  is  an  example  of  the  package,  providing  minimal  functionality. 
—  This  package  may  be  tailored  to  the  needs  of  a  given  platform. 

SQL_Databaee_Error  :  exception; 

SQLCODE  :  SQLCODE_TYPE ; 

—  Parameterless  function  returning  an  error  message  of  type 
SQL_Char_Not_Null . 

—  The  error  message  is  the  descriptive  string  associated  with 
—  the  most  recent  database  error .  It  is  produced  by  a 
—  DBMS  specific  function. 

function  SQL_Database_Error_Message  return  SQL  Char_Not  Null; 
end  SQL_Communications  Pkg; 


C.6  SQL_Communications_Pkg  Body 

—  SQL_Caasmmicationa_Pkg  is  a  "platform-specific"  package 
--  within  the  SAME 

—  this  particular  version  of  the  package  was  developed  for 

a  platform  consisting  of  the  Verdix  (Version  5.41)  Ada  compiler 

—  and  INGRES  (Version  5.0)  running  on  a  Vax  Station 
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with  ayatam;  uaa  ayatam; 

with  SQL  Syatam;  uaa  SQL_Sy»tem; 

with  ingraa_c_aupport;  uaa  ingrea_c_aupport; 

—  ingraa  c  aupport  containa  functiona  Add_Null  and  Strip_Null 

—  which  ir«  uaad  to  eonvart  batwaan  'c'  format  atringa  and 

—  Ada  format  atringa.  Xt  ia  not  includad  in  tha  SAME  atandard  package*, 
package  body  SQL_Communicationa_Pkg  ia 

function  SQL_Databa**_Error_M**aage  ratum  SQL_Char_Not_Null  ia 
Maaaaga_Buffar  :  SQL_Char_Not_Null  ( 1 .. MAXERRLEN ) ; 

Lan  :  intagar  :=  MAXERRLEN; 

procadura  gatarrmag  (Maaaaga  :  in  Add raaa; 

Langth  :  in  Addraaa) ; 

pragma  interface (C,  gatarrmag,  "_aqlarrmag" ) ; 
begin 

gatarrmag  (Maaaaga_Buffar' Addraaa,  Lan ' Addraaa) ; 

—  tha  aaaumption  hara  ia  that  no  arror  will  occur  whan 

—  retrieving  tha  arror  maaaaga  from  tha  databaaa 

ratum  atrip_null (Maaaaga_Buf f ar) ; 
and  SQL_Databaaa_Error_Maaaaga ; 


and  SQL_Communicationa_Pkg; 


C.7  SQL_Exceptions  Specification 

paakage  SQL_axcaptiona 

ia 

Null  VaXua  Error  :  exception ; 
and  SQL_axcaptiona ; 


C.8  SQL_Boolean_Pkg  Specification 

package  SQL  Boole  an _ P  k  g 

ia 

type  Boolaan_with_Onknown  ia  (FAI^E,  UNKNOWN,  TRUE) ; 

-  Three  valued  Logic  oparationa  — 

-  three-val  X  three-val  =>  three-val  — 

function  "not"  (Left  :  Boolean_with_Unknown) 
ratum  Boolaan_with_Unknown; 

—  pragma  INLINE  ("not"); 

function  "and"  (Left,  Right  :  Boolean_with_Unknown) 
ratum  Boolean_with_Unknown; 

—  pragma  INLINE  ( " and " ) ; 

function  "or"  (Left,  Right  :  Boolean_with_Unknown) 
ratum  Boolean  with  Unknown; 
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—  pragma  INLINE  ("or"); 

function  "xor"  (Left,  Right.  :  Boolean  with  Unknown) 
return  Boolean_with  Unknown ; 

--  pragma  INLINE  ("xor"); 

-  three-val  =>  bool  or  exception  - 

function  To_Boolean  (Left  :  Boolean_with_Unknown)  return  Boolean ; 

—  pragma  INLINE  (To_Boolean) ; 

-  three-val  =>  bool  - 

function  Ia_True  (Left  :  Boolean_with_Unknown)  return  Boolean; 

—  pragma  INLINE  (I«_True) ; 

function  Ia_False  (Left  :  Boolean_with_Unknown)  return  Boolean; 

—  pragma  INLINE  (Ia_Falae) ; 

function  Is_Unknown  (Left  :  Boolean_with  Unknown)  return  Boolean ; 

—  pragma  INLINE  (Ia_Unknown) ; 

end  SQL  Boolean  Pkg; 


C.9  SQL  Boolean  Pkg  Body 

With  SQL_Exceptiona ; 

package  body  SQL_Boolean_Pkg  ia 

Null_Value_Error  :  exception  renames  SQL_Exceptione . Null_Value_Error ; 

function  "not"  (Left  :  Boolean_with__Unknown) 
return  Boolean_with_Unknown  ia 

begin 

cate  Left  ia 

when  true  ->  return  falae ; 
when  false  =>  return  true; 
when  unknown  =>  return  unknown; 

end  case; 

end; 

function  "and"  (Left,  Right  :  Boolean  with_U nknown ) 
return  Boolean_with_Unknown  ia 

begin 

if  (Left  =  Falae)  or  elae  (Right  w  Falae)  then 
return  Falae; 

elaif  (Left  *  Unknown)  or  elae  (Right  *=  Unknown)  then 
return  Unknown; 

elae 

return  True; 
end  if ; 
end; 

function  "or"  (Left,  Right  :  Boolean_with_Unknown) 
return  Boolean  with  Unknown  ia 

begin 

if  (Left  =  True)  or  elae  (Right  =  True)  then 
return  True; 

elaif  (Left  =  Unknown)  or  elae  (Right  =  Unknown)  then 
return  Unknown ; 

elae 

return  Falae ; 
end  if ; 
end; 
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function  "xor"  (Loft,  Right  :  Boolean_with  Unknown) 
return  Boolean  with  Unknown  is 

begin 

return  (Left  and  not  Right)  or  (not  Left  and  Right) ; 

and; 


-  three-val  =>  bool  or  exception  - 

function  To_Boolean  (Left  ;  Boolean_with_Unknown)  return  Boolean  ia 
begin 

if  Left  *  Unknown  then  raiaa  null_value_error; 
alee  return  (Left  =  True)  ; 
end  if; 
end; 


-  three-val  =>  bool  - 

function  Is_True  (Left  :  Boolean_with  Unknown)  return  Boolean  ia 
begin 

return  (Left  =  True) ; 

end; 

function  Ia_Falae  (Left  :  Boolean_with_Unknown)  return  Boolean  is 
begin 

return  (Left  =  False) ; 

end; 

function  Is_Unknown  (Left  :  Boolean_with_Unknown)  return  Boolean  is 
begin 

return  (Left  *=  Unknown)  ; 

end; 

end  SQL_Boolean_Pkg; 


C.10  SQL  Int  Pkg  Specification 

with  SQL_Standard; 

with  SQL_Boolean_Pkg;  use  SQL_Boolean_Pkg; 
with  SQL_Char_Pkg;  use  SQL_Char  Pkg; 
package  SQL_Int_Pkg 

is 

type  SQL_Int_not_null  is  new  SQL_Standard . Int; 

-  Possibly  Null  Integer  - 

type  SQL_Int  is  limited  private; 

function  Null_SQL_Int  return  SQL_Int; 

—  pragma  INLINE  (Null_SQL_Int ) ; 

—  this  pair  of  functions  convert  between  the 

—  null-bearing  and  non -null -bearing  types, 
function  Hithout_Null  Base (Value  :  SQL_Int) 

return  SQL_Int_Not_Null; 

—  pragma  INLINE  (Without_Null_Base) ; 

—  With_Null_Base  raises  Null_Value__Error  if  the  input 

—  value  is  null 

function  Hith_Null_Base (Value  :  SQL  Int_Not_Null) 
return  SQL_Int; 

—  pragma  INLINE  (With_Null_Base) ; 

—  this  procedure  implements  range  checking 

—  note :  it  is  not  meant  to  be  used  directly 

—  by  application  programmers 

--  see  the  generic  package  SQL  Int_Ops 
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—  raises  constraint  srror  if  not 

(First  <=  Right  <=  Last) 
procsdurs  Assign  with  check  ( 

Lsft  in  out  SQL_Int;  Right  SQL_Int; 

First,  Last  SQL_Int_Not_Null) ; 

—  pragma  INLINE  (A*sign_with_check) ; 

—  ths  following  functions  implement  thrss  valued 

arx throstle 

—  if  sithsr  input  to  any  of  thasa  functions  is  null 

—  ths  function  raturns  ths  null  valus;  othsrwiss 

—  thsy  perform  ths  indicated  operation 
--  these  functions  raise  no  exceptions 
function  "+" (Right  :  SQL_Int)  return  SQL  Int; 

—  pragma  INLINE  ("+") ; 

function  "-"(Right  :  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("-"); 

function  "abs" (Right  :  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("abs"); 

function  "+" (Left,  Right  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("+"); 

function  "*"(Left,  Right  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("*"); 

function  "-"(Left,  Right  :  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("-"); 

function  "/"(Left,  Right  :  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("/"); 

function  "mod"  (Left,  Right  :  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("mod") ; 

function  "ram"  (Left,  Right  ;  SQL_Int)  return  SQL_Int; 

—  pragma  INLINE  ("rem"); 

function  "**”  (Left  :  SQL_Int;  Right:  Integer)  return  SQL_Int; 

—  pragma  INLINE  (”**"); 

—  simulation  of  ' IMAGE  and  'VALUE  that 

—  retura/take  SQL_Char [_Not_Null]  instead  of  string 

function  IMAGE  (Left  :  SQL_Int_Not_Null)  return  SQL_Char_Not_Null; 
function  IMAGE  (Left  :  SQL_Int)  return  SQL_Char; 

function  VALUE  (left  :  SQL_Char_Not_NUll)  return  SQL_Int_Not_Null; 
function  VALUE  (left  :  SQL_Char)  return  SQL_Int; 

—  Logical  Operations  — 

—  type  X  type  =>  Boolean  with  unknown  -- 

—  these  functions  implement  three  valued  logic 

—  if  either  input  is  the  null  value,  the  functions 

return  the  truth  value  UNKNOWN;  otherwise  they 
perform  the  indicated  comparison. 

—  these  functions  raise  no  exceptions 

function  Equals  (Left,  Right  SQL_Int)  return  Boolean_with_Unknown; 

—  pragma  INLINE  (Equals) ; 

function  Not_Equals  (Left,  Right  :  SQL_Int) 

return  Boolean  with  Unknown; 

—  pragma  INLINE  (Not_Equals) ; 

function  "<"  (Left,  Right  :  SQL  Int)  return  Boolean  with  Unknown; 

—  pragma  INLINE  ("<"); 

function  ">"  (Left,  Right  SQL_Int)  return  Boolsan_with_Unknown; 

—  pragma  INLINE  (">") ; 

function  "<="  (Left,  Right  :  SQL_Int)  return  Boolsan_with_Unknown; 

—  pragma  INLINE  ( "<=" ) ; 

function  ">="  (Left,  Right  SQL_Int)  return  Boolean_with_Unknown; 

—  pragma  INLINE  (">="); 

--  type  =>  boolean  -- 
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function  Is__Null (Value  :  SQL_Int)  return  Boolean; 

--  pragma  INLINE  (Is_Null); 

function  Not_Null (Value  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  (Not_Null) ; 

—  These  functions  of  class  type  =>  boolean 

—  equate  UNKNOWN  with  FALSE.  That  is,  they  return  TRUE 

—  only  when  the  function  returns  TRUE.  UNKNOWN  and  FALSE 

—  are  mapped  to  FALSE . 

function  (Left,  Right  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  ("=") ; 

function  "<"  (Left,  Right  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  ("<"); 

function  ">"  (Left,  Right  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  (”>”); 

function  "<="  (Left,  Right  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  ("<="); 

function  ">«=''  (Left,  Right  :  SQL_Int)  return  Boolean; 

—  pragma  INLINE  (">="); 

—  this  generic  is  instantiated  once  for  every  abstract 

domain  based  on  the  SQL  type  Int. 

—  the  three  subprogram  formal  parameters  are  meant  to 

default  to  the  programs  declared  above . 

—  that  is,  the  package  should  be  instantiated  in  the 

—  scope  of  a  use  clause  for  SQL_Int_Pkg . 

—  the  two  actual  types  together  form  the  abstract 

domain . 

—  the  purpose  of  the  generic  is  to  create  functions 

which  convert  between  the  two  actual  types  and  a 
procedure  which  implements  a  range  constrained 
assignment  for  the  null-bearing  type. 

—  the  bodies  of  these  subprograms  are  calls  to 

—  subprograms  declared  above  and  passed  as  defaults  to 
the  generic . 

generic 

type  With_Null_type  is  limited  private; 
type  Without_null_type  is  range  O ; 

with  function  With_Null_Baae (Value  :  SQL_In+"  Not_Null) 
return  With_Null_Type  is  <>; 
with  function  Without_Null_Base (Value  :  Wi th_N ul l_Type ) 
return  SQL_Int_Not_Null  is  <>; 
with  procedure  A*sign_with_check  ( 

Left  :  in  out  With_Null  Type;  Right  :  With_Null_Type; 
First,  Last  :  SQL_Int_Not_Null)  is  O; 
package  SQL_Int  Ops  is 

function  With_Null  (Value  :  Without_Null_type) 
return  With_Null_type  ; 

—  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without_Null_type ; 

—  pragma  INLINE  (Without_Null) ; 

procedure  assign  (Left  :  in  out  With  null_Type; 

Right  :  in  With_null_type) ; 

—  pragma  INLINE  (assign) ; 
end  SQL_Int_Ops; 

private 

type  SQL_Int  is  record 

Is_Null:  Boolean  :=  true; 

Value;  SQL  Int  Not  Null; 
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and  record; 


end  SQL  Int_Pkg; 


C.11  SQL_int_Pkg  Body 

with  SQL_exception« ; 
package  body  SQL_Int_pkg  ia 

Null  Value  Error  :  exception  rename*  SQL_exceptiona . null_value_error ; 

function  Without_Null_Baa* (Valua  SQL_Int) 
return  SQL_Int_Not_Null  ia 
begin 

if  Value . Ia_Null  then 

raiae  Null_Value_error ; 

elae 

return  Value. Value; 
end  if ; 

end  Without_Null_Baae; 

function  With_Null_Baae (Value  :  SQL_Xnt_Not_Null) 
return  SQL_Int  ia 
begin 

return (Falae,  Value); 
end  With_Null_Baae ; 

procedure  Aaaign_with_check  ( 

lie  ft  :  in  out  SQL_Int;  Right  ;  SQL_Int; 

Fir  at,  Laat  :  SQL_7.nt_Not_Null)  ia 
begin 

if  Right . Ia_null  then  Left . ia_null  : =  True; 
elaif 

(Right .Value  <  Firat  or  elae 
Right. Value  >  Laat)  then 

raiae  Conetraint  Error; 

elae 

Left  :  =■  Right; 
end  if; 

end  Aaaign_With_Check; 

function  Null_SQL  Xnt  return  SQL  Int  ia 
Null_Holder  :  SQL_Int; 
begin 

return  (Null  Holder) ;  —  reliea  on  default  expreaaion  for  Is_Null 
end  Null_SQL_Int ; 

function  "+" (Right  :  SQL_Int)  return  SQL_Int  ia 
begin 

return  Right  ; 

end; 

function  (Right  :  SQL_Int)  return  SQL_Int  ia 
begin 

return  (Right. Ie_Null,  - (Right .Value) ) ; 

end; 

function  "aba" (Right  :  SQL_Int)  return  SQL_Int  ia 
begin 

return  (Right . Ia_Null,  aba (Right .Value)); 
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and; 


function  "+"  (Loft,  Right  :  SQL__Int )  r»tum  SQL_Int  i« 
bogin 

if  Loft . I»_Null  or  Right . Is_Null  thon 
rotum  Null_SQL_Int ; 

oloo 

rotum  (Foloo,  (Loft .  Valuo  +  Right . Voluo) ) ; 
and  if; 

and; 

function  (Loft,  Right  :  SQL_Int)  rotum  SQL_Int  io 
bagin 

if  Laft.Io_Null  or  Right . I«_Null  thon 
rotum  Null  SQL_Int; 

oloo 

rotum  (Foloo,  (Loft. Voluo  *  Right .  Voluo)  )  ; 
and  if; 

and; 

function  (Loft,  Righc  :  SQL_Int)  rotum  SQL_Int  io 
bogin 

if  Loft.Io_Null  or  Right . Io_Null  thon 
rotum  Null_SQL_Int; 

oloo 

rotum  (Foloo,  (Loft.  Voluo  -  Right  .Voluo)  )  ; 
and  if ; 

and; 

function  "/"(Loft/  Right  :  SQL_Int)  rotum  SQL_Int  io 
bogin 

if  Laft.Xa_Null  or  Right. Io  Null  thon 
rotum  Null_SQL_Int; 

oloo 

rotum  (Foloo,  (Loft. Voluo  /  Right. Voluo) ) ; 
and  if; 

and; 

f unction  "mod"  (Loft,  Right  :  SQL_Int)  rotum  SQL_Int  io 
bogin 

if  Loft.Zo_Null  or  Right . Io_Nu 11  thon 
rotum  Null_SQL_Int; 

oloo 

rotum  (Foloo,  (Loft. Voluo  mod  Right .Voluo) ) ; 
and  if; 

and; 

function  "ran"  (Loft,  Right  :  SQL_Int)  rotum  SQL_Int  io 
bogin 

if  Loft . Io_Null  or  Right . Io_Null  thon 
rotum  Null  SQL_Int ; 

oloo 

rotum  (Foloo,  (Laft . Voluo  ran  Right  .Voluo) )  ; 
and  if; 

and; 

function  "**"  (Loft  :  SQL_Int;  Right:  Intogor)  roturn  SQL_Int  io 
bogin 

if  Loft . Io_Null  thon 

rotum  Null_SQL  Int; 

oloo 

rotum  (Foloo,  (Loft. Voluo  **  Right)); 
and  if; 
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end; 


function  IMAGE  (Left  :  SQL_Int_Not_Null)  return  SQL_Char_Not_Null  is 
begin 

return  to_SQL_Char_Not_Null  ( SQL_Int_Not_Null '  IMAGE  (Left)  )  ; 
end  IMAGE; 

function  IMAGE  (Left  :  SQL_Int)  return  SQL_Char  ia 
begin 

if  not  Left . Is_Null  then 

return  to_SgL_Char (SgL_Int_Not_Null' IMAGE (Left .Value) ) ; 

elae 

return  Null_SgL_Char ; 
end  if ; 
end  IMAGE ; 

function  VALUE  (Left  :  SgL_Char_Not_NUll)  return  SQL_Int_Not_Null  ia 
begin 

return  SQL_Int_Not_Null ' VALUE (to_String (Left) ) ; 
end  VALUE; 

function  VALUE  (Left  :  SgL_Char)  return  SQL_Int  ia 
begin 

if  Not_Hull (Left)  then 

return  With_Null_Baaa (SQL_Int__Not_Null' Value (to_String (Left) ) ) ; 

elae 

return  Null_SQL_Int ; 
end  if; 
end  VALUE; 

—  Logical  Operationa  — 

—  type  X  type  =>  Boolean_with_unknown  — 
function  Equal  a  (Left,  Right  :  SQL_Int)  return  Bool»an_with_Unknown  ia 
begin 

if  La£t.Ia_Null  or  Right . Ia_Null  then 
return  Unknown ; 

elae 

if  (Left. Value  *=  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if ; 

end; 

function  Not_Equala  (Left,  Right  :  SQL_Int) 

return  Boolean  with  Unknown  is 

begin 

if  Left.Is_Null  or  Right. Is  Null  then 
return  Unknown; 

else 

if  (Left. Value  =  Right. Value)  then 
return  False; 

else 

return  True; 
end  if; 
end  if; 

end; 

function  "<"  (Left,  Right  SQL__Int)  return  Boolean_with_Unknown  is 
begin 

if  Left.Is_Null  or  Right. Is  Null  then 
return  Unknown; 


CMU/SEI-89-TR-1 6 


153 


•la* 

if  (Left. Value  <  Right. Value)  than 
return  True ; 

•la* 

return  Fala«; 
end  if; 
end  if ; 

end; 

function  ”>"  (Left,  Right  :  SQL_ Int)  return  Boolean  with  Unknown  ia 
begin 

if  Left.Za_Mull  or  Right . 2a_Null  then 
return  Unknown; 

elae 

if  (Left. Value  >  Right. Value)  then 
return  True; 

•  lae 

return  Falae ; 

•nd  if; 
end  if; 

•nd; 

function  "<="  (Left,  Right  SQL  Int)  return  Boolean  with_Unknown  ia 
begin 

if  Left.Xa_Null  or  Right . Ia_Null  then 
return  Unknown ; 

•lee 

if  (Left. Value  <=  Right. Value)  then 
return  True; 

elae 

return  Falae; 

•nd  if; 

•nd  if; 

•nd; 

function  ">*”  (Left,  Right  :  SQL_Int )  return  Boolean_with_Unknown  ia 
begin 

if  Left . Ia_Null  or  Right . Ia_Null  then 
return  Unknown ; 

elae 

if  (Left. Value  >=  Right .Value)  then 
return  True; 

elae 

return  Falae ; 

•nd  if; 
end  if; 

end 


—  type  =>  boolean  — 

function  Ia_Null (Value  :  SQL_Int)  return  Boolean  ia 
begin 

return  Value . Ia_Null ; 
end  I*_Null; 

function  Hot_^ull (Value  :  SQL_Int)  return  Boolean  ia 
begin 

return  not  Value . Ia_Mull; 
end  Not_Null ; 

function  (Left,  Right  ;  SQL_Int)  return  Boolean  ia 

begin 

if  L*ft.Ia_Null  or  elae  Right . Ia_Null  then 
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ratum  FALSE; 

alaa 

rtturn  Laft. Valua  = 
•nd  if; 

•nd 

function  "<"  (Laft,  Right  : 
bagin 

if  Laft.Ia_Null  or  alia 
ratum  FALSE; 

alaa 

ratum  Laft .  Valua  < 
and  if; 
and  "<"; 

function  (Laft,  Right  ; 

bagin 

if  Laft .  Ia_Nu.ll  or  alaa 
ratum  FALSE; 

alaa 

ratum  Laft. Valua  > 
and  if; 
and  ">" ; 

function  "<="  (Laft,  Right 
bagin 

if  Laft . Ia_Null  or  alaa 
ratum  FALSE; 

alaa 

ratum  Laft. Valua  <= 
and  if; 

and 

function  ">="  (Laft,  Right  : 
bagin 

if  Laft . Ia_Null  or  alaa 
ratum  FALSE; 

alaa 

ratum  Laft. Valua  >* 
and  if; 
and  ">*"  ; 


Right . Valua; 

SQL_Int)  ratum  Boolaan  ia 
Right . Ia_Null  than 

Right .Valua; 

SQL  Int)  ratum  Boolaan  ia 
Right . Ia_Null  than 

Right .Valua; 

SQL_Int)  ratum  Boolaan  ia 
Right . Ia_Null  than 

•  Right. Valua; 

>QL_Int)  ratum  Boolaan  ia 
Right . Is_Null  than 

■  Right. Valua; 


packaga  body  SQL_Int_Opa  ia 

function  Nith_Null  (Valua  :  Without_Null_typa) 
ratum  With_Null  typa  ia 
bagin 

ratum  (With_Null_Baaa ( SQL_Int_Not_Null  (Valua) )  )  ; 
and  With_Null; 

function  Without_Null  (Valua  :  With_Null_Typa) 
ratum  Without_Null_Typa  ia 
bagin 

ratum  (Without_null_Typa  ( 

SQL_Lnt_Not_Null '  (Without_Null_Baaa (Valua) ) ) )  ; 
and  Without  Null; 


procadura  aaaign  (Laft  :  in  out  With_null  Typa; 

Right  :  in  With_null_typa)  ia 


bagin 

Aaaign_With_Chack (Laft ,  Right , 

SQL_Int_Not_Null (Without_Null_Typa ' FIRST) , 
.  SQL~Int~Not_Null (Without_Null~Typa ' LAST) ) ; 


and  aaaign; 


and  SQL  Int_Opa; 
and  SQL_Int_Pkg; 
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C.12  SQL_Smallint_Pkg  Specification 

with  SQL_Stsndsrd  ; 

with  SQL  Boolssn_Pkg;  urns  SQL_Boolssn_Pkg; 
with  SQL_Ch»r_Pkg;  us*  SQL_Chsr_Pkg; 
pscksgs  SQL_Smsllint_Pkg 

is 

hyps  SQL_Sm»llint_not_null  is  nsw  SQL_Stsndsrd.Smsllint; 

-  Possibly  Mull  Xntsgsr  - 

typs  SQL_Smsllint  is  limitsd  privsts; 

function  Null_SQL  Smsllint  rsturn  SQL_Sms 1 lint ; 

—  prsgms  INLINE  (Null_SQL_Smsllint) ; 

—  this  psir  of  functions  convsrts  bstwssn  ths 

null-bsmring  and  non-null -bsaring  typss . 
function  Without_Null_Bsss (V&lus  :  SQL_Smsllint) 
rsturn  SQL_Smsllint_Not_Null ; 

—  prsgms  INLINE  (Without_Null_Bsss) ; 

—  With_Null_Bsss  rsisss  Null_Vslu#_Error  if  ths  input 
vslus  is  null 

function  With_Null_Bs«s (Vslus  :  SQL_Sms 1 lint_N ot  Null) 
rsturn  SQL_Smsllint; 

—  prsgms  INLINE  (With_Null_Bs«s ) ; 

—  this  procsdurs  implsmsnts  rsngs  chocking 

—  nots:  it  is  not  mssnt  to  bs  ussd  dirsctly 

by  spplicstion  progrsmmsrs 

—  sss  ths  gsnsric  pscksgs  SQL_Smsllint_Op 

—  rsisss  constrsint_srror  if  not 

(First  <*  Right  <<=  Lsst) 
procsdurs  Assign_with_chsck  ( 

Lsft  :  in  out  SQL_Sms 1 lint ;  Right  :  SQL_Smsllint ; 

First,  Lsst  :  SQL_Smsllint_Not_Null) ; 

—  prsgms  INLINE  (Assign_with_chsck) ; 

—  ths  following  functions  implsmsnt  thrss  vslus d 

—  srithmstic 

—  if  sithsr  input  to  sny  of  thsss  functions  is  null 

ths  function  rstums  ths  null  vslus;  othsrwiss 

—  thsy  psrform  ths  indicstsd  opsrstion 

—  thsss  functions  rsiss  no  sxcsptions 

function  "+" (Right  :  SQL_Smsllint)  rsturn  SQL_Sms I lint ; 

—  prsgms  INLINE  ("+"); 

function  .ight  :  SQL_Smsllint)  rsturn  SQL_Smsllint ; 

—  prsgms  INLINE  ("*") ; 

function  "sbs” (Right  :  SQL_Smsllint)  rsturn  SQL_Smsl lint ; 

—  prsgms  INLINE  ("sbs") ; 

function  "+" (Lsft,  Right  :  SQL  Smsllint)  rsturn  SQL  Smsllint; 

—  prsgms  INLINE  ("+"); 

function  (Lsft,  Right  :  SQL_Smsllint)  rsturn  SQL_Sms 1 lint ; 

—  prsgms  INLINE  (”*"); 

function  (Lsft,  Right  :  SQL_Smsllint)  rsturn  SQL_Smsllint ; 

—  prsgms  INLINE  ("-"); 

function  "/"(Lsft,  Right  :  SQL_Smsllint)  rsturn  SQL_Smsllint; 

—  prsgms  INLINE  (”/") ; 

function  "mod"  (Lsft,  Right  :  SQL_Smsllint)  rsturn  SQL_Smsllint; 

--  prsgms  INLINE  ("mod"); 

function  "ram"  (Lsft,  Right  :  SQL_Smsllint)  rsturn  SQL_Smsllint; 

—  prsgms  INLINE  ("ram") ; 

function  "**"  (Lsft  :  SQL_Smsllint ;  Right:  Intsgsr)  rsturn  SQL_Smsllint; 
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—  pragma  INLINE  (”**”); 

—  simulation  of  'IMAGE  and  'VALUE  that 

—  return/take  SQL_Char  [_Not_Null]  inataad  of  string 

function  IMAGE  (Lsft  :  SQL_Smallint_Not_Null)  rsturn  SQL_Char_Not_Null ; 
function  IMAGE  (Lsft  :  SQL_Smallint)  rsturn  SQL_Char; 

function  VALUE  (Lsft  :  SQL_Char_Not_Null)  rsturn  SQL_Smallint_Not_Null ; 
function  VALUE  (Lsft  :  SQL__Char)  rsturn  SQL_Smallint; 

—  Logical  Opsrations  — 

—  typs  X  typs  =>  Boolean_with_unknown  — 

—  thsss  functions  implsmsnt  thrss  valusd  logic 

—  if  sithsr  input  is  ths  null  value,  the  functions 

—  rsturn  tbs  truth  valus  UNKNOWN;  otherwise  thsy 

—  perform  tbs  indicatsd  comparison. 

—  thsss  functions  raiss  no  exceptions 

function  Equals  (Lsft,  Right  :  SQL_Sraallint)  rsturn  Boolean_with_Unknown; 

—  pragma  INLINE  (Equals) ; 

function  Not_Equals  (Left,  Right  :  SQL_Smallint) 

rsturn  Boolean_with_Unknown; 

—  pragma  INLINE  (Not_Equals) ; 

function  "<"  (Left ,  Right  ;  SQL_Smallint)  rsturn  Boolsan_with  Unknown; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Lsft,  Right  :  SQL_Smallint )  rsturn  Boolsan_with_Unknown; 

—  pragma  INLINE  (">"); 

function  "<="  (Lsft,  Right  :  SQL_Smallint)  rsturn  Boolsan_with_Unknown ; 

—  pragma  INLINE  ("<="); 

function  ">="  (Lsft,  Right  :  SQL_Smallint)  rsturn  Boolsan_with  Unknown ; 

—  pragma  INLINE  (">=") ; 

—  typs  =>  boolean  — 

function  Is_Null (Valus  :  SQL_Smallint)  rsturn  Boolean; 

—  pragma  INLINE  (Is_Null) ; 

function  Not_Null (Valus  :  SQL_Smal lint)  rsturn  Boolsan; 

—  pragma  INLINE  (Not_Null) ; 

—  Thsss  functions  of  class  typs  *=>  boolsan 

—  squats  UNKNOWN  with  FALSE.  That  is,  thsy  rsturn  TRUE 

—  only  when  ths  function  rstums  TRUE .  UNKNOWN  and  FALSE 

—  are  mappsd  to  FALSE . 

function  "a"  (Lsft,  Right  :  SQL_Smallint )  return  Boolsan; 

—  pragma  INLINE  ("=") ; 

function  "<"  (Left,  Right  :  SQL_Smallint )  return  Boolsan; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Lsft,  Right  :  SQL_Smallint)  rsturn  Boolsan; 

—  pragma  INLINE  (">”); 

function  "<="  (Lsft,  Right  :  SQL  Smallint)  return  Boolsan; 

—  pragma  INLINE  ("<=”); 

function  ">="  (Left,  Right  :  SQL  Smallint)  rsturn  Boolsan; 

—  pragma  INLINE  (">=") ; 

—  this  generic  is  instantiated  ones  for  every  abstract 

—  domain  based  on  ths^  SQL  typs  Smallint . 

—  ths  thrss  subprogram  formal  parameters  are  meant  t 3 

—  default  to  ths  programs  declared  above. 

—  that  is,  ths  package  should  be  instantiated  in  ths 

—  scops  of  a  use  clause  for  SQL_Smallint  Pkg. 

—  ths  two  actual  types  together  form  ths  abstract 

—  domain . 

—  ths  purpose  of  ths  generic  is  to  create  functions 

—  which  convert  between  ths  two  actual  types  and  a 

—  procedure  which  implements  a  range  constrained 
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—  assignment  for  the  nulj.-baari.ng  type . 

—  the  bodies  of  these  aubprograms  art  calls  bo 

subprograms  declared  abovs  and  passed  as  defaults  bo 

—  bhs  generic . 
generic 

type  Wibh_Null_bypa  Is  1 imibsd  privaba; 
bypa  Wibhoub_null_bypa  is  range  O ; 

with  function  Wibh_Null_Basa (Value  :  SQL_Smallint_Not_Null) 
rabum  With_Null_Type  is  <>; 
with  function  Without_Null_Basa (Value  :  With_Null_Type) 
return  SQL_Smallint  Not  Null  is  O; 
with  procedure  Assign  with_chack  ( 

Left  :  in  out  Wi th_N u 1 l_Type ;  Right  :  With_Null_Type; 
First,  Last  :  SQL_Smallint_Not_Null)  is  O; 
package  SQL_Smallint_OPs  is 

function  With_Null  (Value  :  Without_Null_type) 
return  With_Null_type; 

—  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without_Null_type ; 

—  pragma  INLINE  (Without_Null) ; 

procedure  assign  (Left  :  in  out  With  null_Type; 

Right  :  in  With_null_type) ; 

—  pragma  INLINE  (assign) ; 
and  SQL_Smallint_ops ; 

private 

type  SQL_Smallint  is  record 
Is_Null:  Boolean  :=  true; 

Value:  SQL_Smallint_Not_Null ; 
end  record; 

end  SQL_Smallint_Pkg; 


C.13  SQL_Smallint_Pkg  Body 

with  SQL_exceptions  ; 

package  body  SQL_Smallint_pkg  is 

Null_Value_Error  :  exception  renames  SQL_exceptions . null  value  error; 

function  Without_Null_Base (Value  :  SQL_Sraallint) 
return  SQL_Smallint_Not_Null  is 
begin 

if  Value . Is_Null  then 

raise  Null  Value_error; 

else 

return  Value . Value ; 

end  if; 

end  Without_Null_Base ; 

function  With_Null_Base (Value  :  SQL_Smallint_Not_Null) 
return  SQL_Smallint  is 
begin 

return (False,  Value) ; 
end  With_Null_Base; 

procedure  Asaign_with_check  ( 

Left  :  in  out  SQL_Smallint ;  Right  :  SQL_Smallint ; 
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First,  Last  :  SQL_Smallint_Not_Null)  is 
begin 

if  Right . Is_Null  than  Left.Is_Null  :=  True; 
alaif 

(Right. Valua  <  First  or  else 
Right. Valua  >  Last)  than 

raisa  Constraint_E rror ; 

alsa 

La ft  : =  Right; 
and  if; 

and  Assign_With_Chack; 

function  Null_SQL_Smallint  rat urn  SQL_Smallint  is 
Mull  Holdar  :  SQL_Smallint; 
bagin 

ratum  (Null  Holdar) ;  —  ralias  on  dafault  axprtssion  for  Is_Null 
and  Null_SQL_Smallint; 

function  "+" (Right  :  SQL_Smallint)  raturn  SQL_Smallint  is 
bagin 

ratum  Right ; 

and; 

function  (Right  :  SQL_Smallint)  raturn  SQL_Smallint  is 
bagin 

ratum  (Right . ls_Null,  - (Right .Value) ) ; 

and; 

function  "ab»" (Right  :  SQL_Smallint)  raturn  SQL_Smallint  is 
bagin 

ratum  (Right . ls_Null,  abs (Right .Value) ) ; 

and; 

function  "+" (Left,  Right  :  SQL_Smallint)  raturn  SQL_Smallint  is 
bagin 

if  Left . Is_Null  or  Right . Is_Null  than 
ratum  Null_SQL_Sma  1 1  int ; 

alsa 

ratum  (Falsa,  (Left.  Valua  +  Right  .Value) )  ; 
and  if; 

and; 

function  (Left,  Right  :  SQL_Smallint)  raturn  SQL_Smallint  is 
bagin 

if  Left . Is_Null  or  Right . Is_Null  than 
ratum  Null_SQL_Sraallint  ; 

alsa 

ratum  (Falsa,  (Left. Valua  *  Right .Value) ) ; 
and  if; 

and; 

function  (Left,  Right  :  SQL_Sroallint)  raturn  SQL  Smallint  is 
bagin 

if  Left.Is_Null  or  Right . Is_Null  than 
ratum  Null_SQL_Smallint ; 

alsa 

return  (Falsa,  (Left. Valua  -  Right .Value) ) ; 
and  if; 

and; 

function  "/" (Left,  Right  :  SQL_Smallint)  ratum  SQL_Smallint  is 
bagin 

if  Left . Is_Null  or  Right . Is_Null  then 
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return  Null  SQL  Smallint ; 

•la* 

return  (Falsa,  (Left. Value  /  Right .Value) ) ; 

•nd  if; 

end; 

function  "mod"  (L«£t,  Right  :  SQL_Smallint)  return  SQL_Smallint  is 
begin 

if  Le£t.Ia_Null  or  Right . I*_Null  then 
return  Null_SQL_Smallint; 

•lee 

return  (False,  (Left .Value  mod  Right . Value) ) ; 
end  if; 

end; 

function  "rem”  (Left,  Right  :  SQL_Sma ] lint )  return  SQL_Smallint  is 
begin 

if  Le£t.Is_Null  or  Right . la_Null  then 
return  Null_SQL_Smallint; 

else 

return  (False,  (Left. Value  rem  Right .Value) ) ; 
end  if; 

end; 

function  "*•"  (Left  :  SQL_Smallint;  Right:  Integer)  return  SQL_Smallint  is 
begin 

if  Left . Is_Null  then 

return  Null_SQL_Smallint; 

else 

return  (False,  (Left .Value  **  Right)); 
end  if; 

end; 

function  IMAGE  (Left  :  SQL_Smallint_Not_Null ) 
return  SQL_Char_Not_Null  is 
begin 

return  to_SQL_Char_Not_Null ( 

SQL_Smallint_Not_Null'  IMAGE  (Left) )  ; 

end  IMAGE; 

function  IMAGE  (Left  :  SQL_Smallint)  return  SQL_Char  is 
begin 

if  not  Left . Ia_Null  then 
return  to_SQL_Char ( 

SQL_Sm*llint_Not_Null ' IMAGE (Left .Value) ) ; 

else 

return  Null_SQL_Ch*r ; 
end  if; 
end  IMAGE; 

function  VALUE  (Left  :  SQL_Char_Not__Null) 
return  SQL_Smallint_Not_Null  is 

begin 

return  SQL_Smailint_Not_Null' VALUE (to_String (Left) ) ; 
end  VALUE; 

function  VALUE  (Left  :  SQL_Ch*r)  return  SQL_Smallint  is 
begin 

if  Not_Null (Left)  then 

return  With_Null_Base ( 

SQL_Smallint_Not_Null' Value (to_String (Left) ) ) ; 

else 

return  Null  SQL  Smallint; 
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and  if ; 
•nd  VALUE ; 


—  Logical  Oparationa  — 

—  fcypa  X  typa  =>  Boolaan_with_Unknown 
function  Equal*  (Laft,  Right  :  SQL_Smallint) 
ratum  Bool*an_with_0nkrown  ia 

bagin 

if  Laft.Ia_Null  or  Right . Ie_Null  than 
ratum  Unknown ; 

alaa 

if  (Laft.Valua  =  Right. Valua)  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

and; 

function  Not_Equala  (Laft,  Right  :  SQL_Smallint) 

ratum  Boolaan_with_Unknown  ia 

bagin 

if  Laft.Ia_Null  or  Right . Ia_Null  than 
ratum  Unknown  ; 

alaa 

if  (Laft.Valua  =  Right. Valua)  than 
ratum  Falaa; 

alaa 

ratum  Trua; 
and  if; 
and  if; 

and; 

function  "<"  (Laft,  Right  :  SQL_Smal lint )  ratum  Boolaan_with_Unknown  ia 
bagin 

if  Laft . I*_Null  or  Right. I a  Mull  than 
ratum  Unknown; 

alaa 

if  (Laft.Valua  <  Right. Valua)  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

and; 

function  ">"  (Laft,  Right  :  SQL__Sma  1 1  int )  ratum  Boolaan_with_Unknown  ia 
bagin 

if  Laft.Ia_Null  or  Right. Ia  Mull  than 
ratum  Unknown; 

alaa 

if  (Laft.Valua  >  Right. Valua)  than 
ratum  Trua ; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

and; 

function  "<="  (Laft,  Right  :  SQL_Smallint)  raturn  Boolaan_with_Unknown  ia 
bagin 

if  Laft.IaJNull  or  Right . Ia_Mull  than 
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rtturn  Unknown; 


alaa 

if  (Left. Value  <=  Right. Value)  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

and; 

function  ">="  (Left,  Right  :  SQL_Smallint)  ratum  Boolean_with_Unknown  ia 
bagin 

if  Left . I«_Null  or  Right . Ia_Null  than 
raturn  Unknown; 

alaa 

if  (Laft . Valua  >=  Right. Value/  than 
raturn  Trua; 

alaa 

ratum  Falaa  ; 
and  if; 
and  if ; 

and; 

function  "="  (Laft,  Right  :  SQL_Smallint)  ratum  Boolean  ia 
bagin 

if  Laft . Ia_Null  or  alaa  Right . Ia_Null  than 
raturn  FALSE ; 

alaa 

ratum  Laft. Valua  =  Right. Valua; 
and  if; 

and 

function  ”<"  (Laft,  Right  :  SQL_Smallint )  ratum  Boolean  ia 
bagin 

if  Laft . Ia_Null  or  alaa  Right . IaJNull  than 
raturn  FALSE ; 

alaa 

raturn  Laft. Valua  <  Right. Valua; 
and  if; 
and  "<"; 

function  ">"  (Laft,  Right  :  SQL_Sma  1 lint )  raturn  Boolean  ia 
bagin 

if  Left.Ia_Null  or  alaa  Right . Ia_Null  than 
return  FALSE; 

alaa 

return  Laft. Valua  >  Right. Value; 
and  if; 

and 

function  "<*"  (Laft,  Right  :  SQL_Smallint)  ratum  Boolean  ia 
bagin 

if  Laft. IaJNull  or  alaa  Right. Ia  Null  than 
ratum  FALSE; 

alaa 

ratum  Left. Valua  <=  Right  .Valua; 
and  if; 
and  "<="; 

function  ">ci"  (1  Right  :  SQL_Smallint)  ratum  Boolean  ia 

bagin 

if  Laft.Ia_Null  or  alaa  Right .  Ia__Null  than 
ratum  FALSE  ; 

alaa 

ratum  Laft. Valua  >=  Right. Valua; 
and  if ; 
and  ">•="  ; 
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-  -  type  =>  boolean  — 

function  ia  Null (Value  :  SQL_Smallint)  return  Boolean  ia 
begin 

return  Value  .  I«_Null  ; 

and; 

function  Not_Null (Valua  :  SQL_Smallint)  return  Boolean  ia 
begin 

return  not  Value . Ia_Null; 

end; 


package  body  SQL_2mallint_0pe  ia 

function  With_Null  (Value  :  Without_Null_type) 
return  With_Null_type  ia 
begin 

return (With_Null_Baae (SQL_Smallint_Not_Null (Value) ) ) ; 
end  Hith_Null; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without  Null^Type  ia 
begin 

return (Without_Null_Type ( 

SQL_Sraallint_Not_Null'  (Without_Null_Baae  (Value)  )  )  )  ; 
end  Without  Null; 


procedure  aaaign  (Left  :  in  out  With_Null_Type; 

Right  :  in  With  Null_type)  ia 


begin 

Aaaign_With_Check (Left ,  Right, 

SQL_Smallint_Not_Null  (Without_Null_Type'  FIRST) 
SQL_Smallint_Not_Null  (Without_Null_Type'  LAST)  ) 

end  aaaign; 


end  SQL_Smallint_opa  ; 
end  SQL_Smallint_Pkg; 


C.14  SQL_Real_Pkg  Specification 

with  SQL  Standard; 

with  SQL_Boolean_Pkg;  uae  SQL_Boolean_Pkg; 
package  SQL_Real_Pkg 

ia 

type  SQL_Real_Not  Null  ia  new  SQL_Standard . Real; 

-  Poaaibly  Null  Real  - 

type  SQL_Real  ia  limited  private ; 

function  Null_SQL  Real  return  SQL  Real; 

—  pragma  INLINE  (Null_SQL_Real) ; 

—  thia  pair  of  functiona  converta  between  the 

—  null-bearing  and  non-null -bearing  typea 
function  Without_Null_Baee (Value  :  SQL_Real) 

return  SQL_Real_Not_Null; 

—  pragma  INLINE  (Without_Null_Baae) ; 

—  With_Null_Baae  raiaea  Null_Value_Error  if  the  input 
value  ia  null 

„  function  With__Null_Baae,  (Value  :  SQL_Real_Not_Null) 
return  SQL  Real; 
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—  pragma  INLINE  (With_Null_Baae) ; 

—  thii  procedure  imp 1 am ant •  ranga  checking 

—  not*:  it  ia  not  meant  to  ba  used  directly 

by  application  programmer* 

—  sea  the  generic  package  SQL_Raal_Op* 

—  raiaaa  ccn*ttaint_arror  if  not 

—  (Firat  <=  Right  <=  Laat) 
procedure  Aaaign  with_Check  ( 

Left  :  in  out  SQL_Real;  Right  :  SQL  Real; 

Firat,  Laat  :  SQL_Real_Not_Null) ; 

—  pragma  INLINE  (A*sign_with_Cheak) ; 

—  the  following  function*  implement  three  valued 

—  arithmetic 

—  if  either  input  to  any  of  theae  function*  ia  null 

—  the  function  return*  the  null  value;  otherwiae 

—  they  perform  the  indicated  operation 

—  theae  function*  raiae  no  exceptions 
function  "+" (Right  :  SQL_Real)  return  SQL_Real; 

—  pragma  INLINE  ("+") ; 

function  (Right  :  SQL_Real)  return  SQL_JReal; 

—  pragma  INLINE  ("-"); 

function  "aba" (Right  :  SQL_Real)  return  SQL_Real; 

—  pragma  INLINE  ("aba"); 

function  "+" (Left,  Right  :  SQL_Real)  return  SQL_Real; 

—  pragma  INLINE  ("+"); 

function  (Left,  Right  :  SQL_Real)  return  SQL_Real; 

—  pragma  INLINE  ( " * " ) ; 

function  "-"(Left,  Right  :  SQL  Real)  return  SQL_Real; 

—  pragma  INLINE  ("-"); 

function  "/"(Left,  Right  :  SQL_Raal)  return  SQL_Real; 

—  pragma  INLINE  ("/"); 

function  "**"(Left  :  SQL_Real;  Right  :  Integer)  return  SQL_Real ; 

—  pragma  INLINE  ("**") ; 


—  Logical  Operation*  — 

—  type  X  type  *=>  Boolean  with_unknown  — 

—  these  function*  implement  three  valued  logic 

—  if  either  input  is  the  null  value,  the  functions 

—  return  the  truth  value  UNKNOWN;  otherwise  they 

—  perform  the  indicated  comparison. 

—  these  functions  raise  no  exceptions 

function  Equal*  (Left,  Right  ;  SQL_R*al)  return  Boolean_with_Unknown; 

—  pragma  INLINE  (Equals) ; 

function  Not  Equal*  (Left,  Right  :  SQL_Real) 

return  Eool*an_with_Unknown; 

—  pragma  INLINE  (Not_Equal.  ) ; 

function  (Left,  Right  :  SQL_Real)  return  Boolean_with_Unknown; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Left,  Right  :  SQL  Real)  return  Boolean  with  Unknown; 

—  pragma  INLINE  (">"); 

function  "<="  (Left,  Right  :  SQL  Real)  return  Boolean  with  Unknown; 

—  pragma  INLINE  ("<="); 

function  ">«=”  (Left,  Right  ;  SQL  Real)  return  Boolean  with  Unknown; 

—  pragma  INLINE  (”>«"); 

—  type  =>  boolean  — 

function  Is  Null (Value  SQL  Real)  return  Boolean; 

—  pragma  INLINE  (I*_Null) ; 

function  Not  Null (Value  :  SQL  Real)  return  Boolean ; 

--  pragma  INLINE  (Not_Null) ; 
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--  The sa  functions  of  class  type  =>  boolean 

—  squats  UNKNOWN  with  FALSE.  That  is,  thsy  return  TRUE 

—  only  whsn  the  function  rstums  TRUE .  UNKNOWN  and  FALSE 
--  ars  mapped  to  FALSE. 

function  "="  (Lsft,  Right  :  SQL__Real)  rstum  Boolean; 

—  pragma  INLINE  ("=") ; 

function  "<”  (Lsft,  Right  SQL  Rsal)  rstum  Boolean; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Lsft,  Right  :  SQL__Real)  rstum  Boolean; 

—  pragma  INLINE  (">") ; 

function  "<="  (Lsft,  Right  :  SQL_Rsal)  return  Boolean; 

—  pragma  INLINE  '("<="); 

function  ”>="  (Lsft,  Right  SQL_Rsal)  return  Boolean; 

—  pragma  INLINE  (">="); 


—  this  gsnsric  is  instantiatsd  ones  for  every  abstract 

domain  bassd  on  ths  SQL  typs  Rsal. 

—  ths  thrss  subprogram  formal  paramstsrs  ars  meant  to 

—  dsfault  to  ths  programs  dsclarsd  above. 

—  that  is,  ths  package  should  bs  instantiatsd  in  ths 

—  scops  of  ths  uss  clauss  for  SQL_Raal  PJcg. 

—  ths  two  actual  typss  togsthsr  form  ths  abstract 

—  domain . 

—  ths  purposs  of  ths  gsn«  vie  is  to  create  functions 

—  which  convert  betwsen  ths  two  actual  typss  and  a 
proesdurs  which  implements  a  range  eonstrainsd 
assignmsnt  for  ths  null-bsaring  typs. 

—  ths  bodiss  of  thsss  subprograms  ars  calls  to 

—  subprograms  dsclarsd  abovs  and  pasaad  as  defaults  to 
ths  gsnsric . 

gsnsric 

typs  With_Null_typs  is  limited  private; 
typs  Without_null_type  is  digits  <>; 

with  function  With_Null_Bass (Value  :  SQL_Rsal_Not_Null ) 
rstum  With_Null_Type  is  <>; 

with  function  Without_Null_Bass (Value  :  With_Null_Type). 

rstum  SQL_Real_Not_Null  is  O; 
with  procedure  Assign  with  check  ( 

Lsft  :  in  out  With_Null_Type ;  Right  :  Wi th_N u 1 l_Type ; 
First,  Last  :  SQL_Rsal_Not_Null)  is  O; 
package  SQL_Rsal_Ops  is 

function  With_Null  (Value  :  Without_Null_typs) 
rstum  With_Null  typs; 

—  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Typs) 
rstum  Without  Null  typs; 

—  pragma  INLINE  (Without_Null)  ; 

,  procedure  assign  (Lsft  :  in  out  With_Null_Type ; 

Right  ;  in  With_Null  typs) ; 

—  pragma  INLINE  (assign) ; 
end  SQL_Real_Ops ; 


private 

typs  SQL_Rsal  is  record 

Is_Null :  Boolean  : =  true; 
Value :  SQL_Rsal_Not_Null ; 
end  record; 

end  SQL_Real_Pkg; 
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C.15  SQJ__ReaI_Pkg  Body 

with  SQL_axcaptions ; 
packaga  Lody  SQL_Raal_pkg  is 

Null_Valua_Error  :  axcapti-  ranamas  SQL_axcaptions . null_valua_atror ; 

function  Without_Null_Baaa (Valua  :  SQL_Raal) 
ratum  SQL_Raal_IJot_Null  ia 
bagin 

if  Valua . I*_Null  than 

xaiaa  Null_Valua_arror ; 

alaa 

ratum  Valua. Valua; 
and  if; 

and  Without_Null_Basa; 

function  With_Null_Basa (Valua  :  SQL_Raal_Not_Null) 
ratum  SQL_Raal  ia 
bagin 

raturn (Falsa,  Valua); 
and  Witb_Null_Baaa ; 

procadura  Aaaign  with  chack  ( 

Laft  :  in  out  SQL_Raal;  Right  :  SQL_Raal; 

Pirat,  Laat  :  SQL_Raal_Hot_Null)  ia 
bagin 

if  Right . Ia_null  than  Laft.i«_null  :=  Tru' ; 
alaif 

(Right. Valua  <  First  or  alaa 
Right. Valua  >  Laat)  than 

raiaa  Constraint  Error; 

alaa 

Laft  : =  Right; 
and  if; 

and  Aaaign_With_Chack ; 

function  Null  SQL_Raal  ratum  SQL  Raal  is 
Null_Holdar  :~SQL_Raal; 
bagin 

ratum  (Null  Roldar) ;  —  ralias  on  dafault  axpraasion  for  Zs_Null 
and  Null__SQL  Raal; 

function  "+" (Right  :  SQL_Raal)  return  SQL_Raal  ia 
bagin 

ratum  Right; 

and; 

function  (Right  :  SQL  Raal)  return  SQL_Raal  is 
bagin 

ratum  (Right  .  Is_Null,  -  (Right  .Valua)  )  ; 

and; 

function  "aba" (Right  :  SQL_Raal)  return  SQL_Raal  ia 
bagin 

ratum  (Right . Ia_Null,  aba (Right .Valua) ) ; 

and; 

function  "+" (Laft,  Right  :  SQL_Raal)  return  SQL  Raal  is 
bagin 

if  Laft.Is_Null  or  Right . la_Null  than 
ratum  Null_SQL  Raal; 

alaa 
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return  (False,  (Left. Value  +  Right. Value) ) ; 

•nd  if ; 

«nd; 

function  "'"(Left,  Right  :  SQL_Real)  return  SQL_Reai  is 
begin 

if  Left . I«_Null  or  Right . Is_Null  then 
return  Null_SQL_Real; 

else 

return  (False,  (Left. Value  *  Right .Value) ) ; 
end  if ; 

end; 

function  (Left,  Right  :  SQL_Real)  return  SQL_Real  is 
begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Null_SQL_Real ; 

else 

return  (False,  (Left. Value  -  Right .Value) ) ; 
end  if; 

end; 

function  "/" (Left,  Right  :  SQL  Real)  return  SQL_Real  is 
begin 

if  Left . Is_Null  or  Right . Is_Null  then 
return  Null_SQL  Real ; 

else 

return  (False,  (Left. Value  /  Right .Value) ) ; 
end  if; 

end; 

function  " ** "  (Left  :  SQL_Real;  Right:  Integer)  return  SQL_Real  is 
begin 

if  Left.Is_Null  then 

return  Null_SQL_Real; 

else 

return  (False,  (Left. Value  **  Right)); 
end  if ; 

end; 


—  Logical  Operations  — 

—  type  X  type  =>  Boolean  with_Unknown  — 
function  Equals  (Left,  Right  :  SQL_Real)  return  Boolean_with  Unknown  is 
begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  =  Right. Value)  then 
return  True; 

else 

return  False ; 
end  if; 
end  if ; 

end; 

function  Not_Equals  "eft,  Right  :  SQL_Real) 

return  Boolean_with_Unknown  is 

begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  =  Right. Value)  then 
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Ktum  False ; 

else 

return  True; 
end  i£; 
end  if  ; 

end; 

function  "<"  (Left,  Right  :  SQL_Real )  return  Boolean_with_Unknown  is 
begin 

i£  Left . Is_Null  or  Right . Ie_Null  then 
return  Unknown ; 

else 

if  (Left. Value  <  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

end; 

function  ">"  (Left,  Right  :  SQL_Real)  return  Boolean_with_Unknown  i# 
begin 

if  Left.Is_Null  or  Right . Ia_Null  then 
return  Unknown; 

else 

if  (Left. Value  >  Right. Value)  then 
return  True ; 

else 

return  False ; 
end  if; 
end  if ; 

end; 

function  "<="  (Left,  Right  :  SQL_Real)  return  Boolean_with_Unknown  is 
begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  <>=  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

end; 

function  ">«”  (Left,  Right  :  SQL_Real)  retxirn  Boolean_with  Unknown  is 
begin 

if  Left . Xs_Null  or  Right . Ia_Null  then 
return  Unknown"; 

else 

if  (Left. Value  ><=  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

end; 

function  (Left,  Right  :  SQL_Real )  return  Boolean  is 

begin 

if  Left . Is_Null  or  else  Right . Is_Null  then 
return  FALSE; 
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•Is* 

rttum  Left. Value  =  Right. Value; 

•nd  if ; 
end  "="; 

function  "<"  (Left,  Right  :  SQL_Real)  return  Boolean  ie 
begin 

if  Left.Ia_Null  or  else  Right . Is_Null  then 
return  FALSE; 

else 

return  Left. Value  <  Right. Value; 
end  if; 

end 

function  ">"  (Left,  Right  :  SQL_Real)  return  Boolean  is 
begin 

if  Left . Ia_Null  or  else  Right . Is_Null  then 
return  FALSE ; 

else 

return  Left. Value  >  Right. Value; 
end  if ; 
end  ">"; 

function  "<="  (Left,  Right  :  SQL_Real)  return  Boolean  is 
begin 

if  Left.Is_Null  or  else  Right . Is_Null  then 
return  FALSE ; 

else 

return  Left. Value  <=  Right. Value ; 
end  if; 

end 

function  "><="  (Left,  Right  :  SQL_Real)  return  Boolean  is 
begin 

if  Left.la_Null  or  else  Right. ls_Hull  then 
return  FALSE ; 

else 

return  Left. Value  >=  Right. Value ; 
end  if; 

end 

—  hype  *=>  boolean 

function  ls_Null (Value  :  SQL  Real)  return  Boolean  is 
begin 

return  Value . Is_Null ; 

end; 

function  Not_Null (Value  :  SQL  Real)  return  Boolean  is 
begin 

return  not  Value . Is_Null; 

end; 

package  body  SQL_Real_Opa  is 

function  With_Null  (Value  :  Without_Null  type) 
return  With_Null  type  is 
begin 

return (With_Null_Ba«e (SQL_Real_Not_Null (Value) ) ) ; 
end  WithJHull; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without_Null  Type  is 
begin 

return (Without_null_Type ( 

SQL_Real_Not_Null' (Without_Null_Base (Value) ) ) ) ; 
end  Without_Null ; 

procedure  aeaign  (Left  :  in  out  With_null  Type; 
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Right  :  in  With_null_type )  ia 

begin 

Assign_With_Check  (La ft ,  Right, 

SQL_Raal_Not_Null (Without_Null_Typa' FIRST) , 
SQL_Rael_Not_Null (Without_Null_Type' LAST) ) ; 

and  aaaign; 
and  SQL_Raal_Opa ; 
and  SQL_Real_P  kg ; 


C.1 6  SQL_Doubie_Precision_Pkg  Specification 

with  SQL_Standard  ; 

with  SQL_Boolean_Pkg;  uaa  SQL_Boolean_Pkg; 
package  SQL _ Doubia _ Pracnion _ P)cg 

ia 

typa  SQL_Doubla_Praciaion_Kot  Null  ia  naw  SQL_Standard .Double_Procision; 

- Poaaibly  Null  Double_Pracision - 

typa  SQL_Double_Precision  ia  limitad  private; 

function  Null_SQL_Doubla_Precision  raturn  SQL  Doubla_P racial on; 

—  pragma  INLINE  (Null_SQL_Doubla_Praci«ion)  ; 

—  thia  pair  of  functiona  convarta  batwaan  tha 

null-bearing  and  non-null -baaring  typaa. 
function  Without_Null_Baaa (Valua  :  SQL_Doubla_Praciaion) 
ra turn  SQL_Doubla_Praciaion_Not_Null ; 

—  pragma  INLINE  ( Without_Null_Baaa ) ; 

—  With_Null_Baaa  raiaaa  Null_Valua_Error  if  tha  input 
valua  ia  null 

function  With_Null__Baae (Valua  :  SQL_Doubla_Praciaion_Not_Null) 
raturn  SQL_Doubla_Praciaion; 

—  pragma  INLINE  (With_Null_Baae ) ; 

—  thia  procadura  implamanta  ranga  checking 

—  nota:  it  ia  not  maant  to  ba  uaad  diractly 

by  application  programs ara 

—  aaa  tha  ganaric  packaga  SQL_Doubla_Praciaion_Op 

—  raiaaa  conatraint_arror  if  not 

(First  <*  Right  <=  Last) 
procadura  Asaign_with_Chack  ( 

Laft  :  in  out  SQL  Doubia  Pracision; 

Right  :  SQL_Doubla_Praciaion; 

First,  Last  :  SQL_Doubla  Precision_Not_Null) ; 

—  pragma  INLINE  (Assign_with_Chack) ; 

--  tha  following  functiona  implamant  thraa  valuad 

—  arithmetic 

—  if  aithar  input  to  any  of  thasa  functions  is  null 

—  tha  function  returns  the  null  valua;  otherwise  they 
perform  tha  indicated  operation 

—  those  functiona  raise  no  exceptions 

function  "+" (Right  :  SQL_Double_Precision)  raturn  SQL_Double_Preciaion; 

—  pragma  INLINE  ("+”); 

function  "-"(Right  :  SQL_Doubla_Praciaion)  raturn  SQL_Double_P re vision; 

—  pragma  INLINE  ("-”); 

function  "aba" (Right  :  SQL_Double_Precision)  raturn  SQL_Double  Precision; 

—  pragma  INLINE  ("aba") ; 
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function  "+" (Left,  Right  SQL_Double_Preciaion) 
return  SQL_Double_Precieion; 

—  pragma  INLINE  ("+"); 

function  (Left,  Right  :  SQL_Double_Preciaion) 

ratucn  SQL_Double_Precision; 

—  pragma  INLINE  ("*") ; 

function  (Laft,  Right  :  SQL_Double_Preciaion) 

ratuxn  SQL_Double_Pracision; 

—  pragma  INLINE  ; 

function  "/" (Laft,  Right  :  SQL_Doubla_Precision) 
ratum  S QL_D oubl a  Precision; 
pragma  INLINE  ("/"); 

function  "**" (Laft  :  SQL_Doubla_Precision;  Right  :  Intagar) 
ratum  SQL  Doubla  Praciaion; 

—  pragma  INLINE  ("**"); 


—  Logical  Oparationa  — 

—  typa  X  typa  =>  Boolean_with_unhnown  -- 

—  thasa  functions  implamant  thraa  valued  logic 

—  if  aithar  input  ia  tha  null  value,  the  functiona 

return  tha  truth  value  UNKNOWN;  otherwise  they 

—  perform  tha  indicated  comparison . 

—  thasa  functions  raise  no  exceptions 

function  Equals  (Laft,  Right  :  SQL_Doubla_Praciaion) 
return  Boolean_with_Unknown; 

—  pragma  INLINE  (Equals) ; 

function  Not_Equals  (Laft,  Right  :  SQL_Double_Precision) 
return  Boolaan_with_Un)cnown; 

—  pragma  INLINE  (Not_Equala) ; 

function  "<"  (Laft,  Right  :  SQL_Double_Precision) 
ratum  Boolaan_with_Unknown; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Laft,  Right  :  SQL_Doubla_Pracision) 
return  Boolean_with_Un)cnown ; 

—  pragma  INLINE  (">") ; 

function  "<="  (Laft,  Right  :  SQL_Doubla_Pracision) 
return  Boolean_with_Unknown; 

—  pragma  INLINE  ( "<=" ) ; 

function  ">="  (Laft,  Right  :  SQL_Doubla_Pracision) 
ratum  Boolaan_with_Un)cnown ; 

—  pragma  INLINE  (">="); 

—  typa  =>  boolean  — 

function  Is_Null (Value  ;  SQL_Double_Precision)  ratum  Boolean; 

—  pragma  INLINE  ( Ia_Null) ; 

function  Not_Null (Value  :  SQL  Doubla_Pracision)  ratum  Boolean; 

—  pragma  INLINE  (Not_Null) ; 

—  Thasa  functions  of  class  typa  =>  boolean 

--  equate  UNKNOWN  with  FALSE.  That  is,  they  ratum  TRUE 

—  only  whan  tha  function  returns  TRUE .  UNKNOWN  and  FALSE 

—  are  mapped  to  FALSE . 

function  "="  (Laft,  Right  :  SQL_Double_Precision)  ratum  Boolean; 

function  "<"  (Laft,  Right  :  SQL_Double_Precision)  ratum  Boolean; 

function  ">"  (Laft,  Right  ;  SQL_Double_Precision)  ratum  Boolean; 

function  "<= "  (Laft,  Right  :  SQL  Doubla  Precision)  return  Boolean; 
function  ”>«="  (Laft,  Right  :  SQL  Doubla_Pracision)  ratum  Boolean; 

—  this  generic  is  instantiated  once  for  every  abstract 

—  domain  based  on  tha  SOL  typa  Double_Precision . 

—  tha  thraa  subprogram  formal  parameters  are  meant  to 

—  default  to  tha  programs  declared  above. 
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—  that  ia,  the  package  ahould  b«  inatant.iat.ad  in  the 

■cope  of  the  uaa  clauaa  for 
SQL_Doubl*_Pr*ciaion_Pkg . 

—  the  two  actual  typaa  together  form  the  abatract 

domain . 

—  the  purpoae  of  the  generic  ia  to  create  functiona 

which  convert  between  the  two  actual  typea  and  a 
procedure  which  implement*  a  range  constrained 
aaaignaent  for  the  null -bearing  type. 

—  the  bodiea  of  theae  aubprograma  are  aalla  to 

—  aubprograma  declared  above  and  paaaed  aa  default* 

—  to  the  generic, 
generic 

type  With_Null_typ*  ia  limited  private ; 
type  Without_null_typ*  ia  digit*  O; 

with  function  With_Null_Baa*  (Value  :  SQL_Doubl*_Pr*ciaion_Not  Null) 
return  With_Null_Type  ia  O; 
with  function  Without_Null  Baa* (Value  :  With_Null_Type) 
return  SQL_Doubl*_Pr#ciaion_Not_Null  ia  O; 
with  procedure  A*aigu_with_ch*ck  ( 

Left  :  in  out  With_Null_Type ;  Right  :  With_Null_Type; 

Firat,  Laat  :  SQL_Doubl*_Pr*ciaion  Not_Null)  ia  O; 
package  SQL_Doubl*_Pr*ci*ion_Opa  ia 

function  With_Null  (Value  :  Without_Null_typ* ) 
return  With_Null_typ* ; 

—  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Type ) 
return  Without_Null_type ; 

—  pragma  INLINE  ( Without_Null ) ; 

procedure  aaaign  (Left  :  in  out  With_null_Typ* ; 

Right  :  in  Hith_null_type) ; 

—  pragma  INLINE  (aaaign); 
end  SQL_Double_Preci*ion_Opa ; 


private 

type  SQL_Double_Preciaion  ia  record 
Ia_Null:  Boolean  : «  true; 

Value:  SQL_Doubl*_Pr*ciaion_Not_Null; 
end  record; 

end  SQL_Doubl*_Preciaion  Pkg; 


C.17  SQL_Double_Precision_Pkg  Body 

with  SQL_exc*ptiona ; 

package  body  3QL_Double_Preciaion_pkg  ia 

Null_Valu*_ErTor  :  exception  rename*  SQL_exc*ptiona . null_value_error ; 

function  Mi thout_N\iU_Baae (Value  :  SQL  Double_Pr*ciaion) 
return  SQL_Doubl*_Pr*ciaion_Not_Null  ia 
begin 

if  Value  .  I*_Null  then 

raiae  Null_Value  error; 

ela* 

return  Val u* . Value ; 
end  if; 

end  Without.  Null  Baae; 
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function  With_Null_Baae (Value  SQL_Double_Preciaion__Not_Null) 
rttum  SQL  Double_Precision  ia 
begin 

ratum  (Falsa,  Value)  ; 
and  With_Null_Base; 

procedure  Assign_with_chec)c  ( 

Left  :  in  out  SQL  Double_Precision;  Right  :  SQL_Double_Precision; 
Firat,  Last  :  SQL  Double_Precision_Not_Null)  is 
begin 

if  Right . Is_Null  than  Left . Is_Null  : =  True; 
alsif 

(Right. Value  <  First  or  else 
Right. Value  >  Last)  than 

raise  Constraint_Error ; 

else 

Left  : =  Right; 
end  if ; 

end  Assign  With_Check; 

function  Null_SQL_Doubla  Precision  return  SQL_Doubla  Precision  is 
Null_Holder  :  SQL__Double_Pracision; 
begin 

return  (Null_Holdar) ;  —  relies  on  default  expression  for  Is  Null 
end  Null_SQL_Double_Pracision; 

function  "4-"  (Right  :  SQL  Oouble_Precision) 
return  SQL_Double_Precision  is 
begin 

return  Right; 

end; 

function  "-"(Right  :  SQL_Double_Precision) 
return  SQL_Double_Precision  is 
begin 

ratum  (Right. Is_null,  - (Right . Value )) ; 

end; 

function  "abs" (Right  ;  SQL_Double_Precision) 
return  SQL_Double  Precision  is 
begin 

return  (Right . Is_null,  abs (Right .Value) ) ; 

end; 

function  "+" (Left,  Right  :  SQL_Double_Precision) 
ratum  SQL_Doubl*_Precision  is 
begin 

if  Left.Is_Null  or  Right. Is  Null  then 
return  Null_SQL  Double_Precision; 

else 

return  (False,  (Left .Value  4-  Right .Value) ) ; 
end  if; 

end; 

function  (Left,  Right  :  SQL_Doubla_Precision) 
return  SQL_Double  Precision  is 
begin 

if  Left.Is_Null  or  Right. Is  Null  than 
return  Null_SQL_Double_Precision; 

else 

return  (False,  (Left. Value  *  Right .Value) ) ; 
and  if; 

end; 
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function  "-"(Loft,  Right  :  SQL_Doublo_Procision) 
ntum  SQL_Doublo_Procision  i« 
bogin 

if  Loft.Zo_Mull  or  Right . Zo_Null  thon 
rotum  Null_SQL_Doublo_Procioion; 

•Iso 

rotum  (Foloo,  (Loft.Voluo  -  Right .Voluo) ) ; 

•nd  if; 

ond; 

function  "/" (Loft,  Right  :  SQL_Doublo_Proci«ion) 
rotum  SQL_Doublo_Proci«ion  is 
bogin 

if  Loft.Zs_Null  or  Right . l*_Null  thon 
rotum  Null_SQL_Doublo_Proci»ion; 

•Iso 

rotum  (Falso,  (Loft.Voluo  /  Right .Voluo) ) ; 

•nd  if; 

•nd; 

function  " ** "  (Loft  :  SQL_Doublo_Procioion;  Right:  Intogor) 
rotum  SQL_Doublo_Procision  is 
bogin 

if  Loft . Zs_Null  thon 

rotum  Null_SQL_Doublo_Proeision; 

•Iso 

rotum  (Folso,  (Loft.Voluo  **  Right)); 

•nd  if; 

ond; 


—  Logical  Oporotions  — 

—  hypo  X  typo  =>  Booloon_with_unknown  — 
function  Equals  (Loft,  Right  :  SQL_Doublo_Procision) 
rotum  Booloon_with_Unknown  is 
bogin 

if  Loft.Zs_Null  or  Right. Zs  Mull  thon 
rotum  Unknown; 

•Iso 

if  (Zioft. Voluo  =  Right. Voluo)  thon 
rotum  Truo; 

•Iso 

rotum  Folso; 

•nd  if; 

•nd  if; 

•nd; 

function  Mot_Equols  (Loft,  Right  :  SQL_Doublo_Procision) 
rotum  Booloon_with_Unknown  is 
bogin 

if  Z^ft.Zs_Null  or  Right . Zs_Nu 11  thon 
rotum  Unknown  ; 

•Iso 

if  (Z<oft. Voluo  =  Right. Voluo)  thon 
rotum  Folso ; 

•  Iso 

rotum  Truo  ; 

•nd  if; 

•nd  if; 

•nd; 

function  ”<"  (Loft,  Right  :  SQL_Doublo_Procision) 
rotum  Booloon  with  Unknown  is 
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begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Oninown  ; 

else 

if  (Left. Value  <  Right. Value)  then 
return  True ; 

•  lee 

return  False; 
end  if; 
end  if; 

end; 

function  ">”  (Left,  Right  :  SQL_Double_Precision) 
return  Boolean_with_Unknown  is 
begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  >  Right. Value)  then 
return  True  ; 

else 

return  False; 
end  if; 
end  if; 

end; 

function  "<="  (Left,  Right  :  SQL_Double_Preciaion) 
return  Boolean_with  Unknown  is 
begin 

if  Left.Is_Kull  or  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  <=  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if ; 

end; 

function  ”>«"  (Left,  Right  :  SQL_Double_Precision) 
return  Boolean_with_Unknown  is 
begin 

if  Left.Is_Null  or  Right . Is_Null  then 
return  Unknown; 

else 

if  (Left. Value  >=  Right .Value)  then 
return  True ; 

else 

return  False; 
end  i f ; 
end  if ; 

end; 


—  type  =>  boolean  — 

function  Is_Null (Value  :  SQL_Double_Precision)  return  Boolean  is 
begin 

return  Value . Is_Null ; 

end; 

function  Not_Null (Value  SQL_Double_Precision)  return  Boolean  is 
begin 
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rttucn  not  Valua . I«_Null ; 

•nd; 

function  "="  (Laft,  Right  :  SQL_Doubla_Praciaion)  r»tum  Boolean  ic 
bagin 

if  Laft.Is_Null  or  alaa  Right .  Is_Null  than 
ratum  FALSE; 

alaa 

ratum  Laft.Valua  <=  Right. Valua; 
and  if ; 

and 

function  "<"  (Laft,  Right  :  SQL_Doubla_P racial on)  ratum  Boolaan  is 
bagin 

if  Laft. Is  Mull  or  alaa  Right . Ia_Null  than 
ratum  FALSE; 

alaa 

ratum  Laft.Valua  <  Right. Valua; 
and  if; 
and  "<"; 

function  ">"  (Laft,  Right  :  SQL_Doubla_Pracision)  ratum  Boolaan  i# 
bagin 

if  Laft.Ia_Null  or  alaa  Right .  Ia_Null  than 
ratum  FALSE; 

alaa 

ratum  Laft.Valua  >  Right. Valua; 
and  if; 

and 

function  "<="  (Laft,  Right  :  SQL_Doubla_Praciaion)  ratum  Boolaan  ia 
bagin 

if  Laft . Is_Null  or  alaa  Right . Ia_Null  than 
ratum  FALSE; 

alaa 

ratum  Laft.Valua  <=  Right. Valua; 
and  if; 
and  "<="; 

function  ">«s"  (Laft,  Right  :  SQL  Doubla_Praciaion)  ratum  Boolaan  ia 
bagin 

if  Laft .  Ia_Null  or  alaa  Right .  Is_Mu.ll  than 
ratum  FALSE; 

alaa 

ratum  Laft.Valua  >*=  Right. Valua; 
and  if ; 

and 

pachag*  oody  SQL  uoubia  Pracision  Op»  is 

function  With_Null  (Valua  :  Without_Null_typa) 
ratum  With_Null  typa  ia 
bagin 

ratum (With_NuJ '  Sasa (SQL_Doubla_Praciaion_Not_Null (Valua) ) ) ; 
and  With_Null; 

function  Without_Null  (Valua  :  With_Mull_Typa) 
ratum  Without  Mull  Typa  ia 
bagin 

ratum  (Without_null_Typa  ( 

SQL_Doubla  Praciaion_Not_Null' (Without_Null_Baaa (Valua) ) ) ) ; 
and  Without_Hull ; 

procadura  assign  (Laft  :  in  out  With_null_Typa ; 

Right  :  in  With_null_typa)  ia 

bagin 

Aaaign_With_Chack (Laft,  Right, 

SQL_Doubla_Praciaion  Not_Null (Without  Null_Typa' FIRST) , 
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SQL_Double_Pracision_Not_Null  (Without_Null_Type '  LAST)  )  ; 

»nd  assign ; 

•nd  SQL_Double_Precision_Ops ; 
end  SQL  Double_Precision_P)cg; 


C.18  SQL_Decimal_Pkg  Specification 

with  SQL  Boolean_P)cg;  use  SQL  Boolean_Pleg; 
with  S QL_I nt_p kg ;  us*  SQL_Int_P)eg; 
with  SQL_Ch*r_Plcg;  uss  SQL_Char_Pkg; 

with  SQL  Double  Precision  PJcg;  uss  SQL_Doubls_Precision  Pkg; 
package  SQL_Dsc ima  1_P k g  is 

—  MAX_DIGITS  is  implementation  defined 

—  It  represents  the  maximum  number  of  digits  that  can  be 

—  stored  in  the  underlying  hardware's  representation  of 
a  BCD  number 

MAX_DIGITS  :  constant  integer  :=  31; 

subtype  decimal_digits  is  natural  range  0 . ,MAX_DIGITS; 

type  SQL_Decimal_Not_Null (scale  :  decimal_digits  :=  0)  is  limited  private; 
type  SQL_Decimal (scale  :  decimal^digita)  is  limited  private; 

subtype  Numaric_Chaa.*ctar  is  Character  range  '0'  ..'9'; 

type  Numeric_String  is  array  (decimal_digits  range  <>)  of  Numeric_Character ; 
type  Sign_Character  is  ('+', 

--  the  following  type  is  used  for  purposes  of  creating  generic 

—  assign  and  rs_in  functions. . . -DO  HOT  OSE  THIS  TYPE  to 

create  the  abstract  domains . 

type  SQL_Decimal_Hot_Null2 (scale  :  decimal_digits  :=  0)  is  limited  private; 

function  To_SQL_Decimal_Hot_Hull  (Value  :  SQL_Decimal_Not_Null2) 
return  SQL_Decimal_Not_Hull; 
function  To_SQL_Decimal  (Value  :  SQL_Decimal_Not_Null2) 
return  SQL_Decimal ; 

function  To_SQL_Decimal_Not_Null2  (Value  :  SQL_Decimal_Not_Hull) 
return  SQL_Decimal_Not_Null2 ; 
function  To_SQL_Decimal_Not_Null2  (Value  :  SQL_Decimal) 
return  SQL_Decimal_Not_Null2 ; 

—  pragma  INLINE (To_SQL_Decimal_Not_Null2) ; 

—  this  function  returns  a  null  value  of  the  SQL_Decimal  type 
function  Null_SQL  Decimal  return  SQL_Decimal; 

—  pragma  INLINE (Null_SQL_Decimal) ; 

—  The  following  functions  shift  the  value  of  the  object 

without  changing  the  scale.  Effectively,  the  operation 

—  mutiplies  the  value  in  the  object  by  10**Scale. 

—  The  following  functions  raise  Constraint_Error  if  the  left 
shift  causes  a  losa  of  significant  digits 
function  Shift  (Value  :  SQL_Decimal_Not_Null; 

Scale  :  integer)  return  SQL_Decimal_Not_Null ; 
function  Shift  (Value  :  SQL  Decimal; 

Scale  ;  integer)  return  SQL_Decimal; 

—  pragma  INLINE (Shift) ; 

--  The  following  functions  return  objects  with  the  appropriate 
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—  value* 

.function  Zero  return  SQL  D#cimal_Not  Null; 
function  Zero  return  SQL  Decimal ; 

—  pragma  INLINE (Zero) ; 

function  On#  return  SQL_D*cimal_Not_Null ; 
function  One  return  SQL_Deci-mal; 

—  pragma  INLINE (One); 

The  following  Aaaignment  procedure  ia  provided  for  the 
SQL  Decimal_Not_Null  type ; 

—  The  following  Aaaignment  procedure  raiaea  Conatraim._Error 

—  if  the  value  of  Right  doea  not  fall  within  the  rang* 
of  lower.. upper 

procedure  A**ign_With_Ch#ck  (Left  ;  in  out  SQL_D*cimal_Not_Null; 

Right  :  SQL_D#cimal  Not_Null : 

Lower,  Upper  :  SQL_D*Cimal_Not_Null2) ; 

—  The  following  Aaaign  with_ch#ck  procedure  will  be  uaed 

—  in  the  generic  Aaaign  produced  in  SQL_D#ciraal  Ope 

—  thia  procedure  raiaea  the  Conatraint  Error  exception  if 

—  the  "Right"  input  parameter  fall#  outside  the  rang* 
defined  by  Lower .. Dpper 

procedure  Aseign_With  Check 

(Left  :  in  out  SQL  Decimal; 

Right  :  SQL_D*cimal; 

Lower,  Upper  :  SQL__D#cimal_Not_Null2) ; 

—  pragma  INLINE (Aaaign_with_eheck) ; 

—  The  following  comparison  operatora  are  provided: 

function  "="  (Left,  Right  :  SQL_D*cimal_Not_Null)  return  boolean; 
function  ”="  (Left,  Right  :  SQL__D*cimal)  return  boolean; 

—  pragma  INLINE ("*" ); 

function  Equal*  (Left,  Right  :  SQL_Decimal)  return  Bool*an_With_Unknown; 

—  pragma  INLINE (Equal*)  ; 

function  Not_Equal*  (Left,  Right  :  SQL_Decimal)  return  Bool*an_With__Unknown; 

—  pragma  INLINE (Not_Equala) ; 

function  "<"  (Left,  Right  SQL_Decimal  Not_Null)  return  boolean; 

function  "<"  (Left,  Right  :  SQL  Decimal)  return  boolean ; 

function  "<"  (Left,  Right  :  SQL_D*cimal)  return  Bool*an_With_Dnknown; 

—  pragma  INLINE ("<" ); 

function  ">"  (Left,  Right  :  SQL_D*cimal_Not_Null)  return  boolean; 

function  ">"  (Left,  Right  :  SQL_D#cimal)  return  boolean ; 

function  ">"  (Left,  Right  :  SQL  Decimal)  return  Boolean  With  Unknown; 

—  pragma  INLINE (">"); 

function  "<="  (Left,  Right  :  SQL_D#cimal__Not_Null)  return  boolean; 

f’xnction  "<="  (Left,  Right  :  SQL  Decimal)  return  boolean; 

function  "<="  (Left,  Right  :  SQL_D*cim*l)  return  Bool#an_With_Unknown; 

—  pragma  INLINE ("<=") ; 

function  ">="  (Left,  Right  :  SQL_Decimal_Not_Null)  return  boolean; 

function  ">="  (Left,  Right  SQL  Decimal)  return  boolean; 

function  ”>="  (Left,  Right  SQL  Decimal)  return  Boolean  With  Unknown; 

—  pragma  INLINE  (">«=")  ; 

—  the  following  function*  are  memberahip  teat* 

the  value  of  the  object  is  tested  to  see  if 
if  it  fall#  within  the  rang*  of  Lower. .Upper 
function  Ia_In_Baa*  (Right  SQL_D*cim*l_Not_Null; 

Lower,  Upper  SQL_Decimal_Not_Null2) 

return  boolean; 

function  Ia_In_Baa*  (Right  SQL_D*cimal; 

Lower,  Upper  :  SQL_D*cimai  Not_Null2) 

return  boolean; 
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--  pragma  INLINi  (la  In_Baae) ; 

function  I#_Null (Valua  :  SQL  Decimal)  return  boolean; 

--  pragma  INLIKE  (Ia_Null); 

function  Not_Null (Value  SQL_Deci mal )  return  boolean; 

--  pragma  INLINE  (Not_Null) ; 

--  The  following  unary  arithmetic  operator!  are  provided: 
function  "4"  (Right  :  SQL  Declmal_Not  Null) 
return  SQL  Decimal_Not  Null; 

function  "4-“  (Right  :  SQL_Decimal)  return  SQL_De c ima  1  ; 
function  (Right  :  SQL_Decimal_Not_Null) 

return  SQL_Decimal_Not_Null; 

function  " - "  (Right  :  SQL_Decimal)  return  SQL_Decimal ; 

f unction  "abe"  (Right  :  SQL_Declmal_Not_Null) 
return  SQL  Decimal  Not_Null; 

function  "aba"  (Right  :  SQL_Decimal)  return  SQL_Decimal; 

--  pragma  INLINE ( "abe" ) ; 

—  The  following  binary  arithmetic  operatora  are  provided; 

--  The  "4"  and  functions  return  a  result  with  a  acale  of 

max (Left . scale.  Right. acale) 

--  If  the  operation  produces  a  reault  that  is  too  large  to 
be  represented  in  an  object  that  has  this  scale,  a 
Const raint_Error  will  be  raised 
function  "4"  (Left,  Right  ;  SQL  Decimal  Not_Null) 
return  SQL_Decimal_Not_Nuil; 

f unction  "4"  (Left,  Right  :  SQL_Decimal)  return  SQL_Decimal ; 

--  pragma  INLINE ("4“); 

function  (Left,  Right  :  SQL_Decimal_Not_Null ) 

return  SQL_Decimal_Not_Null; 

function  (Left,  Right  :  SQL_Decimal)  return  SQL_Decimal; 

--  pragma  INLINE ( " - " )  ; 

—  The  function  returns  a  result  with  the  scale 

Left. scale  4  Right . scale 

--  If  the  result  is  too  large  to  be  represented  in  an  object 
that  has  this  aaale ,  Canetraint_Error  will  be  raised 
function  (Left,  Right  :  SQL  Decimal_Not_Null) 

return  SQL_Decimal_Not_Null; 

function  (Left ,  Right  :  SQL_Decimal)  return  SQL_Declmal ; 

—  The  "/"  function  returns  a  result  with  as  much  scale  as 

possible,  given  the  nature  of  the  result 

—  If  the  reault  is  too  large  to  be  represented  in  the 

the  underlying  hardware  or  in  an  object  with  no  scale, 
or  if  an  attempt  is  made  to  divide  by  sero,  the 
Conatraint_Error  exception  will  be  raised 
function  "/"  (Left,  Right  :  SQL  DeciaaI_Not  Null) 
return  SQL_Dec imal_N ot_Nul 1 ; 

function  ”/n  (Left,  Right  :  SQL_Decimal)  return  SQL_Decimal; 

—  The  following  mixed  mode  operators  are  provided: 

function  (Left  :  SQL_Decimal_Not_Null;  Right  :  SQL_Int_Not_Null) 

return  SQL  Decimal  Not_Null; 

function  (Left  :  SQL_Decimal;  Right  :  SQL_Int_Not_Null ) 

return  SQL_Decimal; 

f unction  (Left  :  SQL_Decimal;  Right  :  SQL_Int) 

return  SQL  Decimal ; 

function  (Left  :  SQL_Int_Not_Null ;  Right  :  SQL_Decimal_Not_Null) 

return  SQL_Decimal_Not_Null; 

function  (Left  :  SQL_Int_Not_Null ;  Right  :  SQL_Decimal) 

return  SQL  Decimal; 

function  ~(Left  ;  SQL  Int;  Right  :  SQL  Decimal) 
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rttam  SQL_Decimal ; 

—  pragma  INLINE  ("*"); 

function  "/"  (Left  :  SQL_Decimal_Not_Null;  Right  SQL_Int_Not_Null) 
rttam  SQL_Decimal_Not_Null; 

function  "/"  (Left  :  SQL_Dec imal ;  Right  SQL_Int_Not_Null ) 

ntum  SQL_Decimal ; 

function  "/"  (Left  :  SQL_Decimal ;  Right  SQL_Int) 
return  SQL_Decimal ; 

■ —  pragma  INLINE  ("/'')  ; 

—  The  following  functions  convert  to  SQL_Decimal_Not_Null; 
function  To_SQL_Decimal_Not_Null  (Right  :  SQL_Int_Not_Null) 

return  S QL_D e c im*_l_N ot_N ul  1 ; 

—  the  following  function  raises  Constraint_Error 

—  if  the  SQL_Double_Precision_Not_Null  value  is  too  large 
to  be  represented  in  BCD  format 

function  To  SQL_Deeimal_Not_Null  (Right  :  SQL_Double_Precision_Not_Null) 
return  SQL_Dec j  ma l_Not_Null ; 

—  the  following  function  raises  Constraint_Error 

—  if  there  are  more  than  MAX_DIGITS  number  of  digits ; 
if  there  are  two  or  more  decimal  points; 

—  if  there  are  two  or  more  sign  designations; 

if  there  exists  a  character  other  than  '0' ..'9'  or  ' 
or  ,  '  '  for  the  sign 

if  the  order  of  the  characters  is  anything  other  than 

—  sign  designation  followed  by  the  number 
function  To_SQL_Decimal_Not_Null  (Right  :  SQL_Char_Not_Null) 

return  SQl_Decimal_Not_Null; 

—  pragma  INLINE  (To_SQL_Decimal__Not_Null)  ; 

—  The  following  functions  convert  to  SQL_Decimal; 

function  To_SQL_Decimal  (Right  :  SQL_Int_Not_Null)  return  SQL_Decimal; 
function  To_SQL_Decimal  (Right  :  SQL_Int)  return  SQL_Decimal; 

—  the  following  two  functions  raise  Constraint_Error 

—  if  the  SQL_Double_Precision_Not_Null  value  is  too  large 
to  be  represented  in  BCD  format 

function  To_SQL_Decimal  (Right  :  SQL_Double_Precision_Not_Null) 
return  SQL_Decimal; 

function  To  SQL_Decimal  (Right  :  SQL_Double_Preciaion)  return  SQL_Decimal; 

—  the  following  two  functions  raise  Const raint_Error 

if  there  are  more  than  MAX_DIGITS  number  of  digits; 

—  if  there  are  two  or  more  decimal  points; 

—  if  there  are  two  or  more  sign  designations; 

—  if  there  exists  a  character  other  than  'O' ..'9'  or  ' 

or  '  for  the  sign 

—  if  the  order  of  the  characters  is  anything  other  than 

—  sign  designation  followed  by  the  number 

function  To_SQL_Decimal  (Right  :  SQL_Char_Not_Null)  return  SQL_Decimal; 
function  To_SQL_Decimal  (Right  :  SQL_Char)  return  SQL_Decimal; 

—  pragma  INLINE (To_SQL_Decimal)  ; 

—  The  following  functions  convert  from  Decimal  to  Integer 
function  To_SQL_Int_Not_Null  (Right  ;  SQL_Decimal_Not_Null) 

return  SQL_Int_Not_Null; 

function  To_SQL_Int_Not_Null  (Right  :  SQL_Decimal) 
return  SQL_Int  Not_Null; 

—  pragma  INLINE (To_SQL_Int_Not_Null) ; 

function  To_SQL_Int  (Right  :  SQL_Decimal)  return  SQL_Int; 

—  pragma  INLINE (To_SQL  Int) ; 

—  The  following  functions  convert  from  Decimal  to  Float : 

function  To_SQL_Doub le_P reci s i on_N ot_N ul 1  (Right  :  SQL__Decimal_Not_Null) 
return  SQL  Double  Precision  Not  Null; 
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function  To_SQL_Double_Preciaion_Not_Null  (Right  SQL_Decimal) 
return  SQL_Doub?  •  Preciaion_Not_Null : 

--  pragma  INLINE  (To_SQL_Doubie  Pr«cmofi_Not_Null)  , 
function  To_SQL_Double_Preciaion  (Right  SQL_Decimal) 
return  SQL_Double_Preciaion; 

--  pragma  INLINE (To  SQL  Double  Precision); 

—  The  following  functions  convert  from  Decimal  to  String: 

function  To_Stnng  (Right  SQL  Decimal  Not  Null)  return  string: 

function  To_String  (Right  SQL  Decimal)  return  string: 

—  pragma  INLINE (To  String) ; 

function  To  SQL_Char  Not_Null  (Right  :  SQL  Decimal  Not_Null) 
return  SQL_Char  Not  Null; 

function  To_SQL_Char_Not  Null  (Right  SQL_Decimal ) 

return  SQL  Char_Not  Null; 

—  pragma  INLINE (To_SQL_Char_Not  Null) ; 

function  To_SQL  Char  (Right  SQL_Decimal)  return  SQL  Char: 

—  pragma  INLINE (To_SQL_Chax ) ; 

—  the  following  functions  return  the  length  of  the  string 

—  value  returned  by  the  "To_String"  function 

function  Width  (Right  SQL  Decimal_Nct_Null )  return  integer: 

—  The  following  function  raises  the  Null_Value_Error  exception 

—  on  the  null  input 

function  Width  (Right  :  SQL_Decimal)  return  integer: 

—  pragma  INLINE (Width) , 

—  The  following  functions  implement  some  of  the  Ada  Attributes 
--  of  the  BCD  type 

—  The  number  of  BCD  digits  be  ore  the  decimal  point  for  the 
--  type  of  the  given  object: 

function  Integral_Digita  (Right  :  SQL_Decunal_Not_Null return  decimal_digits  ; 
function  Integral_Digits  (Right  :  SQL_Decimal)  return  decimal_digits ; 

—  pragoa  INLINE (Integral_Digita) ; 

—  The  number  of  BCD  digits  after  the  decimal  point  for  the 

—  type  of  the  given  object: 

function  Scale  (Right  :  SQL_Decimal_Not_NuI_l)  return  decimal_digita ; 
function  Scale  (Right  SQL_Decimal)  return  decimal_digits; 

—  pragma  INLINE  (Scale)'; 

—  The  actual  number  of  BCD  digits  before  the  decimal  point  for 

—  a  given  object  of  a  given  type: 

function  Fore  (Right  :  SQL_Decimal_Not  Null)  return  positive; 

—  The  following  function  raises  the  Null_Value_Error  on  the  null  input 
function  Fore  (Right  :  SQL_Decimal)  return  positive; 

--  pragma  INLINE (Fore) ; 

—  The  number  of  BCD  digits  after  the  decimal  point  for  a 

—  given  object  of  a  given  type : 

function  Aft  (Right  SQL_Decimal_Not_Null)  return  positive ; 

—  The  following  function  raises  the  Null_Value  Error  on  the  null  input 
function  Aft  (Right  :  SQL_Decimal )  return  positive; 

—  pragma  INLINE  (Aft); 

function  Machine_Rounds  (Right  SQL_Decimal_Not_Null)  return  boolean; 
function  Machine_Rounds  (Right  SQL_Decimal)  return  boolean; 

—  pragma  INLINE (Machine  Rounds); 

function  Machine_Overf lows  (Right  :  SQL_Decimal_Not_Null )  return  boolean; 
function  Machine_Overf lows  (Right  SQL_Decimal)  return  boolean; 

—  pragma  INLINE (Machine  Overflows); 
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generic 

type  With_Null_Type (acala  :  decimal_digita)  ia  limited  private; 
tvoa  Without  Null  Tvsa(2sala  decimal  dicrita)  ia  limitad  private; 
in_ac*la  :  dacim*l_digita  :=  0; 

firat_aign  :  Sign_Charactar  :=  '  -  '  ; 

£irat_integral  :  Numeric_String  := 

(1. . decimal_digita' laat-in_acala  =>  '9'); 
firat_fractional  :  Numeric_String  := 

( 1 .  , in_acala  =>  '  9 '  )  ; 
laat_aign  :  Sign  Character  := 

laat_integral  :  Numeric_String  := 

(1. .dacimal_digita'  laat-in_acala  =>  ' 9' ) ; 
laat_fractional  :  Numaric_String  := 

( 1 . . in_acala  =>  '  9 '  )  ; 

with  function  Ia_ln_Baaa  (Right  :  Without_Null_Type ; 

Lowar,  Dppar  :  SQL_Decimal_Not_Null2) 

return  boolean  ia  O; 

with  function  Ia_In_Baaa  (Right  :  With_Null_Typa ; 

Lowar,  Dppar  :  SQL_Decimal_Not_Null2) 

return  boolean  ia  O ; 
with  procadura  Aaaign  with  check 

(Laft  :  in  out  Withouh_Null_Type ; 

Right  :  Without_Null_Type; 

Lowar,  Dppar  :  SQL_Decimal_Not_Null2) 
ia  <>; 

with  procadura  Aaaign_with  chack 

(Laft  :  in  out  With_Null  Type; 

Right  :  With_Null_Typ« 

lower,  Dppar  :  SQL  Decimal_Not_Null2) 
ia  O; 

with  function  To_SQL_Decimal_Not_Null2  (Valua  :  Without_Null_Type ) 
return  SQL_Decimal_Not_Null2  ia  O; 
with  function  To_SQL_Decimal_Not  Null2  (Valua  :  With_Null_Type) 
return  S QL_D ec ima 1_N ot_N ul 12  ia  O; 
with  function  To_SQL_Decimal_Not_Null  (Valua  :  SQL_Decimal_Not_Null2) 
return  Without_Null_Typa  ia  O; 
with  function  To_SQL_Dac 1 mal  (Valua  :  SQL_Dacimal_Not_Null2 ) 
return  With_Null_Type  ia  <>; 
package  SQL_Decimal_Opa  ia 

procadura  Aaaign  (Laft  :  in  out  Without_Null_Type ; 

Right  :  Without_Null_Typa ) ; 
procedure  Aaaign  (Laft  :  in  out  With_Null_Type; 

Right  :  With_Null_Typa) ; 

—  pragma  INLINE (Aaaign) ; 

function  Ia_In (Right  :  W±thout_Null_Type ) 
return  boolean; 

function  Ia_In(Right  :  With_N’\l  Type) 
return  boolean; 

—  pragma  INLINE (Ia_In) ; 

function  With_Null  (Valua  :  Wit*.  r_Null_Type) 
return  With_Null_Typa ; 

—  pragma  INLINE (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without_Null_Type ; 

—  pragma  INLINE (Without_Null_Type) ; 
end  SQL_Dacimal_Opa ; 

private 

—  The  requirement  hare  ia  to  provide 

—  at  laaat  enough  apace  for  the  machine  rapraaantation  of  the 
—  SQL_Decimal_Not_Null  operanda . 
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—  type  Digit  i«  picked  to  be  an  integer  type  with  a  range 

that  will  force  the  Ada  compiler  to  pick  a 
pre-defined  integer  type  from  package  Standard. 

type  Digit  is  range  -  (2**7)  ..  (2**7) -1; 

—  the  following  object  is  declared  so  that  the  true  size 

(in  actual  number  of  bits  allocated)  is  assignee  to  the 

—  "size”  object,  rather  than  the  number  of  bits  used  of 
these  which  are  allocated.  In  other  words,  using  'size 

—  on  the  type  Digit  yields  4  bits  (number  bits  used) , 

—  whereas  using  the  'size  on  "object"  (of  type  Digit)  yields 
6  bits  (number  bits  allocated) 

abject  :  Digit; 

--  size  is  the  number  of  bits  used  by  each  object  of  type  Digit 

—  it  is  used  in  the  calculation  of  MAX  SIZE  (below) 

size  constant  integer  :  =  object' size; 

—  MAX  SIZE  is  the  number  of  array  positions  needed  for  the 
Max_Decimal  type  below 

—  since  each  BCD  digit  can  fit  into  4  bits  of  storage,  the 

—  total  number  of  bits  can  be  calculated  by  MAX_DIGITS  *  4; 

—  this  result  is  divided  by  the  number  of  bits  that  an  object 

—  of  type  Digit  will  comprise,  which  yields  the  number  of 

—  array  positions  needed  for  the  BCD  number 

—  the  result  is  incremented  by  one  to  accomodate  the  sign 

MAX_SIZE  :  constant  integer  :=  ((4  *  (MAX_DTCITS) )  /  size)  +  1; 

—  Max_Decimal  is  the  array  type  definition  used  by  the 

SQL_Decimal_Not_Null  type  definition  (below)  to  allocate  maximum 
storage  for  its  BCD  value 

type  Max_Decimal  is  array  (1 . .MAX_SIZE)  of  Digit; 

—  SQL_Decimal_Not_Null  is  the  Ada  BCD  type.  It  is  comprised  of  a  BCD 
value  which  resides  in  an  object  which  reserves  maximum 
space  for  BCD  values,  and  a  scale  which  indicates  how 

—  many  digits  exist  to  the  right  of  the  decimal  point  in  the 
BCD  value 

type  SQL_Decimal_Not_Null  (scale  :  decimal  digits  : «=  0 )  is  record 
Value  :  Max_T)ecimal; 
end  record; 

type  SQL_Dec i ms ) _Not_Null2  (seals  :  decimal_digits  :*  0)  is  record 
Value  :  Max_Decimal; 
end  record; 

type  SQL_Decimal (scale  :  decimal_digita)  is  record 
Is_Null  ;  boolean  : =  true; 

Value  :  SQL_Decimal_Not_Null (scale) ; 
end  record; 

end  SQL_Decimal_Pkg; 
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C.19  SQL_Decimal_Pkg  Body 

with  text  io;  use  text  io; 
with  unchecked  conversion; 
rrith  SQL_Exceptions; 
with  SQL_Standard; 
package  body  SQL_D«cimal_Pkg  is 

—  th»  following  type  i«  used  to  convert  all  other  integer 

types  to  the  underlying  hardware  integer  representation 

—  used  by  the  computer  to  convert  between  integers 
and  packed  decimal  numbers 

type  BCD_Int_Type  is  range  -  (2**31)  (2**31) -1 ; 

Null_value_Error  :  exception  renames  SQL_Exceptions . null_value_error ; 
package  £io  is  new  float_io (float) ;  use  fio; 

package  SQL_DPNN_io  is  new  f loat_io (SQL_Double_Precision_Not_Null) ; 
use  SQL  DPNN  io; 

use  SQL_Standard.Character_Set; 

—  interfaced  assembler  routines 


—  this  procedure  converts  the  integer  in  Right  to  a  BCD  value 
procedure  integer_to_decimal  (Value  :  in  out  Max_Decimal; 

Right  :  BCn_Int_Type) ; 

pragma  interface  (assembler,  integer_to_decimal) ; 
pragma  import_procedure  ( xnteger_to_decimal , "I2D", 

(Max_Decimal,  BCD_Int_Type )  ,  Reference)  ; 

—  this  procedure  converts  the  BCD  value  in  Right  to  an  integer 
procedure  decimal_to_integer  (Value  :  in  out  BCD_Int_Tvpe ; 

Right  :  Max_Decimal; 
error  :  in  out  boolean) ; 

pragma  interface  (assembler,  decimal_to_int» ger) ; 
pragma  inport_procedure  (decimal_to_integer,  "D2 1", 

(BCD  Xnt  Type, Max_Decimal, boolean) , Reference) ; 

—  this  procedure  converts  a  string  representation  of  a  BCD  value 

into  a  BCD  value 

procedure  numeric_string_to__decimal  (Value  ;  in  out  Max_Decimal; 

Right  :  SQL_Char_Not_Null) ; 

pragma  interface  (assembler,  numer  ic__str  ing_to_decimal ) ; 
pragma  import_procedure  (numeric_string_to_decimal , "NS2D", 

(Max_Decimal,  SQL_Char_Not_Null)  , 

Reference) ; 

--  this  procedure  converts  a  BCD  value  to  a  string  representation 
of  that  value 

procedure  decimal  to  numeric  string  (Value  :  in  out  SQL_Char_Not_Sull ; 

Right  :  Max  Decimal ) ; 

pragma  interface  (assembler,  decimal_to_numeric_string) ; 
pragma  import_procedure  (decimal_to_numeric_string, "D2NS" , 

(SQL_Char_Not_Null, Max_Decimal) , Reference) ; 

—  this  procedure  returns  the  number  of  leading  zeroes  in  the 

first  "integ"  digits  of  the  BCD  value 
procedure  leading_zeroes  (Value  :  Max  Decimal; 

integ  :  integer; 
digs  :  in  out  integer) ; 
pragma  interface  (assembler,  leading_zeroes) ; 
pragma  import_procedure  (leading_zeroes, "LZ" , 
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(Majc_D®cimal ,  integer,  integer)  , 

Rtftrutca)  ; 

—  this  procedure  return*  th«  number  of  trailing  zeroes  in  the 

lest  "seal"  digits  of  the  BCD  value 
procedure  trailing_zeroe*  (Value  :  Max  Decimal; 

seal  :  decimal  digits; 
digs  :  in  out  integer) ; 
pragma  interface  (assembler,  trailing  zeroes); 
pragma  import_procedure  (trailing  zeroes, "TZ", 

(Max_Deciraal,  decimal  digits, 
integer) , Reference) ; 

—  this  procedure  interprets  the  sign  of  the  BCD  value,  and 

—  negates  it 

procedure  inverse  (Value  :  in  out  Max_Decimal; 

Right  :  Max_Decimal) ; 
pragma  interface  (assembler,  inverse) ; 
pragma  import__procedure  (inverse, " INV" , 

(Max_Decimal, Max_Deciroal) , 

Reference) ; 

—  this  procedure  returns  the  absolute  value  of  the  BCD  value 
procedure  absv  (Value  :  in  out  Max  Decimal ; 

Right  :  Max_Decimal) ; 
pragma  interface  (assembler,  absv) ; 
pragma  import_jproc®dure  (absv,  "ABSV" , 

(Max_Decimal,  Max_Decimal) , 

Reference) ; 

—  this  procedure  shifts  the  input  value  by  "scale"  powers  of  10 

—  if  "scale"  is  positive,  the  shift  is  left;  else  the  shift  is 

right 

procedure  shft  (Result  :  out  Max_Decimal; 

Value  :  Max_Decimal ; 
scale  :  integer ; 
error  :  in  out  boolean) ; 
pragma  interface  (assembler,  shft) ; 
pragma  import_prooedure  (shft,  "SHFT" , 

(Max_D*cimal , Max_Decimal, integer, boolean)  , 
Reference) ; 

—  this  procedure  determines  if  Left  and  Right  are  equal 
procedure  equal  (Left,  Right  :  Max  Decimal; 

result  :  in  out  boolean) ; 

pragma  interface  (assembler,  equal) ; 
pragma  import_procedure  (equal, "EQ", 

(Max_Decimal, Max_Decimal, boolean) , 
Reference) ; 

—  this  procedure  determines  if  Left  is  <  Right 
procedure  less  than  (Left,  Right  :  Max  Decimal ; 

result  ;  in  out  boolean) ; 

pragma  interface  (assembler,  less  than) ; 
pragma  import_procedure  (less  than, "LT", 

(Max_Decimal , Max_Decimal, boolean) , 
Reference) ; 

—  this  procedure  determines  if  Left  >  Right 
procedure  greater_than  (Left,  Right  :  Max  Decimal; 

result  :  in  out  boolean) ; 
pragma  interface  (assembler,  greater_than) ; 
pragma  import_procedure  (greater_than, "GT" , 
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(Max  Dacimal, Max  Dacuul ,  boolean)  , 
Rafaranca) ; 

—  this  procadura  datarminaa  i£  La ft  <=  Right 
procaduia  lasa_than_aqual  (Laft,  Right  Max_Dacimal; 

raault  :  in  out  boolaan) ; 

pragma  intarfaaa  (aaaamblar,  laaa_than_aqual ) ; 
pragma  import_procadura  (laaa_than_aqual , "LEQ" , 

(Max  Dacimal, Max_Dacimal, boolaan) , 
Rafaranca) ; 

—  thia  procadura  datarminaa  if  Laft  >a  Right 
procadura  graatar_than_aqual  (Laft,  Right  :  Max_Dacimal; 

raault  in  out  boolaan)  ; 

pragma  intarfaaa  (aaaamblar,  graatar_than_aqual) ; 
pragma  import_jprocadura  (graatar_than_aqual, "GEQ " , 

(Max  Dacimal, Max_Oacimal, boolaan) , 
Rafaranca) ; 

—  thia  procadura  adda  Laft  and  Right,  and  atoraa  tha  raault 

in  Raault 

—  tha  "arror"  boolaan  ia  aat  to  trua  on  ovarflow 
procadura  add  (Raault  :  in  out  Max_Dacimal; 

Laft,  Right  :  Max_Dacimal; 
arror  :  in  out  boolaan) ; 
pragma  intarfaaa  (aaaamblar,  add) ; 
pragma  import_procadura  (add,  "ADD", 

(Max_Dacimal , Max_Dacimal , 
Max_Dacimal, boolaan) , Rafaranca) ; 

—  thia  procadura  aubtracta  Right  from  Laft,  storing  tha 

—  raault  in  Raault 

—  tha  "arror"  boolaan  xb  aat  to  trua  on  ovarflow 
procadura  subtract  (Raault  :  in  out  Max_Dacimal ; 

Laft,  Right  :  Max_Dacimal ; 
arror  :  in  out  boolaan) ; 
pragma  intarfaaa  (aaaamblar,  subtract) ; 
pragma  import_procadura  (subtract, "SOB", 

(Max_Dacimal,  Max_Dacimal, 
Max_Dacimal, boolaan) , Rafaranca) ; 

—  this  procadura  multiplias  Laft  by  Right,  and  atoraa  tha 

raault  in  Raault 

—  tha  "arror"  boolaan  is  aat  to  trua  on  ovarflow 
procadura  multiply  (Raault  :  in  out  Max_Dacimal; 

Laft,  Right  :  Max_Dacimal; 
arror  :  in  out  boolaan) ; 
pragma  intarfaaa  (aaaamblar,  multiply) ; 
pragma  in^aort^ procadura  (multiply,  "MOL"  , 

(Max_Dacimal,  Max_Dacimal, 

Max  Dacimal, boolaan) , Rafaranca) ; 

—  thia  procadura  dividas  Laft  by  Right,  storing  tha  raault 

in  Raault 

procadura  divida  (Raault  :  in  out  Max_D a cima 1 ; 

Laft,  Right  :  Max_Dacimal; 

Shift  :  in  out  intagar; 
arror  :  in  out  boolaan) ; 

pragma  intarfaca  (aaaamblar,  divida) ; 
pragma  import_procadura  (divida, "DIV" , 

(Max  Dacimal, Max_Dacimal, 
Max_Dacimal , intagar, boolaan) , 
Rafaranca) ; 
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function  max  (Loft,  Right  :  dacimal  digits)  ntum 
dscimal_digits  is 
bagin 

if  Laft  >£=  Right  than 
ntum  Laft; 

•Isa 

ntum  Right; 
and  if; 
and  max; 

function  To_SQL_Dacimal_Not_Null  (Valua  :  SQL_Dacimal_Not_Null2 ) 
ntum  SQL_Dacimal_Not_Null  is 
bagin 

ntum  (Valua.  scaia,  Valua  .Valua)  ; 
and  To_SQL_Dacimal_Not_Null; 

function  To_SQL_Dacimal  (Valua  :  SQL_Dacimal_Not_Null2) 
ntum  SQL_Dacimal  is 
bagin 

ntum  (Valua . scaia,  Falsa,  To_SQL_Dacimal_Not_Null (Valua) ) ; 
and  To_SQL_Dacimal; 

function  To_SQL_Dacimal_Not_Null2  (Valua  :  SQL_Dacimal_Not_Null) 
ntum  SQL_Dac imal_N ot_N ul  12  is 
bagin 

ntum  (Valua .  scaia ,  Valua .  Valua )  ; 
and  To_SQL_Dacimal_Not_Null2  ; 

function  To_SQL_Dacimal_Not_Null2  (Valua  :  SQL_Dacimal) 
raturn  SQL_Dacimal_Not_Null2  is 
bagin 

if  Valua . Is_Null  than 

raiaa  null_valua_arror ; 

•Isa 

raturn  To_SQL_Dacimal  Hot  Null2 (Valua. Valua) ; 
and  if; 

and  To_SQL_Dacimal_Not_Null2 ; 

function  Null_SQL_Dacimal  raturn  SQL_Dacimal  is 
Null_Holdar  ;  SQL_Dacimal (0) ; 
bagin 

raturn  Null_Holdar; 
and  Null_SQL_Dacimal; 

function  Shift  (Valua  :  SQL_Dacimal_Not  Null; 

Seal*  :  intagar)  raturn  SQL_Dacimal_Not_Null  is 
Roldar  :  SQL_Dacimal_Not_Null  :=  Valua; 

•rror  :  boolaan  :=  falsa; 
bagin 

shft  ( Roldar .Valua,  Valua. Valua,  Scaia,  arror) ; 
if  arror  than 

raisa  Constraint  Error; 
and  if ; 

raturn  Holdar; 
and  Shift ; 

function  Shift  (Valua  :  SQL  Dacimal; 

Scaia  :  intagar)  raturn  SQL_Dacimai  is 

bagin 

if  Valua . Is_Null  than 

raturn  Null  SQL  Dacimal; 
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•la* 

r«tum  (Valua . acil*,  False,  Shift (Value . Value,  Scale)); 

•nd  if; 

•nd  Shift ; 

function  Zero  ratum  SQL  Decimal  Not  Null  ia 
begin 

return  To_SQL_Decimal_Not_Null (0) ; 
end  Zero ; 

function  Zero  return  SQL_Decimal  ia 
begin 

return  (0,  False,  Zero) ; 
end  Zero; 

function  One  return  SQL_Decrmal_Not_Null  ia 
begin 

return  To_SQL_Decimal_Not_Null (1) ; 
end  One ; 

function  One  return  SQL  Decimal  ia 
begin 

return  (0,  False,  One); 
end  One : 

procedure  Assign_With_Check  (Left  in  out  SQL_Decimal_Not_Null ; 

Right  SQL_Decimal  Not_Null; 

Lower,  Dp per  ;  SQL_Decimal__Not_Null2)  ia 
Holder  ;  SQL_Decimal_Not_Null; 
error  :  boolean  : =  false; 
begin 

if  Right  >=  To_SQL_Decimal_Not_Null (Lower)  and  then 
Right  <=  To_SQL_Decimal_Not_Null (Upper)  then 
if  not  (Left  ,  scale  w  Right  ,  scale)  then 

shft (Holder .Value,  Right. Value,  (Left . scale  -  Right . scale) , 
error) ; 

Left .  Value  :  *=  Holder  .  Value ; 

else 

Left  :*  Right; 
end  if; 

else 

raise  Constraint_Error ; 
end  if ; 

end  Assign_With_Check; 

procedure  Aasign_with_check 

(Left  :  in  out  SQL_Decimal ; 

Right  SQL_Decimal; 

Lower,  Upper  :  SQL_Decimal_Not_Null2)  is 
Holder  :  SQL  Decimal_Not_Null; 
error  ;  boolean  :=  false; 
begin 

if  Riaht . Ie_Null  then 

Left .  Is_Null  : «=  True; 

else 

if  Right .Value  >«  To_SQL_Decimal_Not_Null (Lower)  and  then 
Right.  Value  <=  To  SQL_Deoiiuii_Not_Null  (Dpper)  then 
Left . ls_Null  :«  False; 

if  not  (Left .Value . scale  *  Right .Value . scale)  then 
shft (Holder . Value ,  Right .Value . Value , 

(Left .Value . seals  -  Right .Value . scale) , 
error) ; 

Left .Value .Value  : =  Holder .Value ; 
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•la* 

Laft. Valua  :=  Right. Valua; 

•nd  if ; 

•la* 

rant  Constraint  Error; 
and  if ; 
and  if; 

and  Assign  with  chacfc; 

+■  -  .cion  (Laft,  Right  SQL  Dacimal  Not  Null)  ratiim  boolean  is 

digs  :  intagar; 

Holdar  :  SQL_Dacimal_Not_Null; 

•rror ,  rasult  ;  boolaan  : *=  falsa; 
bagin 

if  Laf  t .  seal*  /■=  Right .  seal*  than 

digs  :  =  abs (intagar (Laft . seals  -  Right . seals) ) ; 
if  Laft . seals  >  Right . seal*  than 

shft  (Holdar .Valua,  Right. Valua,  digs,  arror); 
if  arror  than 

raturn  Falsa; 
and  if ; 

•qual  (Laft. Valua,  Holdar . Valua ,  rasult); 

•Isa 

shft  (Holdar .Valua,  Laft. Valua,  digs,  arror); 
if  arror  than 

raturn  Falsa ; 
and  if ; 

•qual  (Holdar .Valua,  Right. Valua,  rasult) ; 
and  if; 

•Isa 

•qual  (Laft. Valua,  Right. Valua,  rasult); 
and  if ; 

raturn  rasult; 
and  "  =  " ; 

function  (Laft,  Right  :  SQL_Dacimal) 

raturn  boolaan  is 
bagin 

if  Laft . Is_Null  or  also  Right . Is_Null  than 
raturn  Falsa ; 

•Isa 

if  (Laft. Valua  *=  Right. Valua)  than 
raturn  Trua; 

•Isa 

raturn  Falsa; 
and  if ; 
and  if; 
and  "  =  " ; 

function  Equals  (Laft,  Right  SQL_Dacimal) 
raturn  Boolaan  With  Unknown  is 
bagin 

if  Laft.Is_Null  or  alsa  Right . Is_Null  than 
raturn  Unknown; 

•Isa 

if  (Laft. Valua  =  Right. Valua)  than 
raturn  Trua; 

•Isa 

raturn  Falsa ; 
and  if ; 
and  if ; 
and  Equals ; 
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function  Not_Equala  (Laft,  Right  :  SQL_Dacimal) 
rttum  BooX««n  With  Unknown  ia 
bagin 

if  Laft.Ia_Null  or  ala*  Right . Ia_  Null  than 
ratum  Unknown ; 

alaa 

if  (Laft.Valua  /=  Right. Valua)  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

and  Not_Equala; 

function  "<"  (Laft,  Right  :  SQL  Dacimal  Not  Null)  ratum  boolaan  ia 
diga  :  intagar; 

Holdar  :  SQL_Dacimal_Not_Null; 
arror,  raault  :  boolaan  : =  falaa; 
bagin 

if  Laf t . acala  /—  Right . acala  than 

diga  :=  aba ( intagar (Laft . acala  -  Right . acala) ) ; 
if  Laft. acala  >  Right. acala  than 

ahft  (Holdar .Valua,  Right. Valua,  dig a,  arror); 
if  arror  than 

if  Right  >  Zaro  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if ; 
and  if; 

laaa_than  (Laft.Valua,  Holdar . Valua ,  raault); 

alaa 

ahft  (Holdar .Valua,  Laft.Valua,  diga,  arror); 
if  arror  than 

if  Laft  <  Zaro  than 
ratum  Trua; 

alaa 

ratum  Falaa; 
and  if; 
and  if; 

laaa_than  (Holdar .Valua,  Right. Valua,  raault); 
and  if ; 

alaa 

laaa_than  (Laft.Valua,  Right. Valua,  raault); 
and  if ; 

ratum  raault; 
and  "<"; 

function  "<"  (Laft,  Right  :  SQL_Dacimal ) 
ratum  boolaan  ia 
bagin 

if  Laft . Ia_Null  or  alaa  Right . Ia_Null  than 
ratum  Falaa  ; 

alaa 

if  (laft .Valua  <  Right .Valua)  than 
ratum  Trua ; 

alaa 

ratum  Falaa; 
and  if ; 
and  if ; 

and  "<"; 

function  ”<”  (Laft,  Right  :  SQL  Dacimal) 
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raturn  Boolaan_With_Un)cnown  is 
bagin 

if  Laft.Is_Null  or  alsa  Right . Is_Null  than 
rttum  Unknown; 

alsa 

if  (Laft. Valua  <  Right. Value)  th  . 
raturn  Tma; 

alaa 

raturn  Filsa; 
and  if; 
and  if; 
and  "<"; 

function  (Laft ,  Right  :  SQL_Dacrmal_Not  _hull)  raturn  boolaan 

digs  :  intagar; 

Holdar  :  SQL_Dacimal_Not_Null; 
arror,  rasult  :  boolaan  :=  falsa; 
bagin 

if  Laft. seals  /=  Right . seals  than 

digs  :=  abs (intagar (Laft . s iala  -  Right . seals) ) ; 
if  Laft. seals  >  Right. seals  than 

shft  (Holdar .Valua,  Right. Valua,  digs,  error) ; 

_ :  arror  than 

if  Right  <  Zaro  than 
raturn  True; 

alsa 

raturn  Falsa; 
and  if; 
and  if; 

g  - '  aata  r_than  (Laft. Valua,  Holdar .Valua,  rasult); 

alaa 

■hft  (Holdar .Valua,  Laft. Valua,  digs,  error) ; 
if  arror  than 

if  Laft  >  Zaro  than 
retu.-n  True: 

alsa 

raturn  Falsa; 
and  if ; 
and  if; 

graatar_than  (Holdar .Value,  Right. Valua,  rasult); 
and  if; 

alsa 

gtaacar_than  (Laft. Valua,  Right. Valua,  rasult) ; 
and  if; 

r a turn  rasult; 

and  ">"; 

function  (Laft,  Right  :  SQL  Dacimal) 

raturn  bools in  is 
bagin 

if  Laft.Is_Null  or  alsa  Right . Is_Null  than 
raturn  False ; 

alsa 

if  (Laft .Valua  >  Right. Valua)  than 
raturn  Trua; 

alsa 

raturn  Falsa; 
and  if; 
and  if ; 

and  ”>"; 

function  (Laft,  Right  SQL  Dactmal) 

raturn  Boolaan  With  Unknown  is 


is 
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begin 

if  Left . Is_Null  or  else  Right . Is_Null  then 
return  Unknown ; 

else 

if  (Left. Value  >  Right. Value)  then 
return  True; 

else 

return  False ; 
end  if; 
end  if; 
end  ">"; 

function  " <= "  (Left,  Right  :  SQL  Decimal _N ot_Hul 1 )  return  boolean  is 
d^.gs  :  integer; 

Bolder  :  S QL_D ec imal _N ot  Hull; 
error,  result  :  boolean  : =  false; 
begin 

if  Left . scale  /=  Right . scale  then 

digs  : =  abs (integer (Left . scale  -  Right . scale) ) ; 
if  Left . scale  >  Right . scale  then 

shft  (Bolder .Value,  Right. Value,  digs,  error); 
if  error  then 

if  Right  >  Zero  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

less_than_equal  (Left. Value,  Bolder .Value,  result); 

else 

shft  (Bolder .Value,  Left. Value,  digs,  error); 
if  error  then 

if  Left  <  Zero  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

less_tban__egual  (Bolder .Value,  Right. Value,  result); 
end  if; 

else 

less_than_equal  (Left. Value,  Right. Value,  result); 
end  if; 

return  result; 
end  "<="; 

function  "<="  (Left,  Right  :  SQL_Decimal) 
return  boolean  is 
begin 

if  Left.Is_Null  or  else  Right . Is_Null  then 
return  *>lse; 

else 

if  (Left. Value  <=  Right. Value)  then 
return  True; 

else 

return  False; 
end  if; 
end  if ; 

end 

function  "<*”  (Left,  Right  :  SQL_Decimal) 

return  Boolean_With_Unknown  is  ' 

begin 
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if  Left  .  Ia_Null  or  ala*  Right  -  Is_Null  then 
rttum  Unknown; 

•la* 

if  (Left. Value  <“  Right . Value)  than 
ntum  True; 

•  1-5 

ntum  False; 
end  if; 
and  if; 

•nd 

function  ">•"  (Lef t ,  Right  :  SQL_Decimal_Hot_Mull )  return  boolean  la 
digs  :  integer ; 

Rold«r  ;  SQL_Decimal_Not_Hull , 

•rror ,  result  :  boolean  : “  false; 
begin 

if  Left . seals  /•  Right . seal*  then 

digs  :•  abs (integer (left . scale  -  Right . scale) ) ; 
if  Left . scale  >  Right . scale  then 

shft  (Bolder .Value,  Right. Value,  digs,  error); 
if  error  then 

if  Right  <  Zero  then 
return  True; 

else 

return  False; 
end  if; 
end  if ; 

greater_than_equal  (Left. Value,  Holder .Value,  result); 

else 

shft  (Holder .Value,  Left. Value,  digs,  error) ; 
if  error  then 

if  Left  >  Zero  then 
return  True; 

else 

return  False; 
end  if; 
end  if; 

greater_than__egual  (Holder .Value ,  Right. Value,  result); 
end  if; 

else 

gxeater_than_equal  (Left .Value,  Right. Value,  result); 
end  if; 

return  result; 

end 

function  ">="  (Left,  Right  ;  SQL_Decimal) 
return  boolean  is 
begin 

if  Left . Is_Null  or  else  Right . IsJNull  then 
return  False ; 

else 

if  (Left. Value  >=  Right. Value)  then 
return  True; 

else 

return  False ; 
end  if; 
end  if; 
end  ">■" ; 

function  (Left,  Right  :  SQL_Decimal) 

return  Boolean_With_Dn known  is 
begin 

if  Lef t . Is_Null  or  else  Right . Is_Null  then 
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return  Unknown ; 


•la* 

if  (Laft. Valua  >•  Right . Valua)  than 
return  Trua; 

•laa 

return  Falsa ; 
and  if; 
and  if; 
and  ">m" ; 

function  Ia_In_B*aa  (Right  :  SQL_Dacimal_Not  Null; 

Lowar,  Dppar  :  SQL_Daeimal_Not_Null2) 

return  boolaan  ia 
bagin 

if  Right  >•  To_SQL_Dacimal_Not_Null (Lowar)  and  than 
Right  <a  To_SQL_Dacimal_Not_Null (Dppar)  than 
ratuxn  Trua; 

•laa 

ratun  Falaa; 
and  if; 

and  Ia_In_Baaa; 

function  Ia_In_B*aa  (Right  SQL_Dacimal; 

Lowar,  Dppar  :  SQL  Dacimal_Not  Null2) 

return  boolaan  ia 
bagin 

if  Right . Ia_Null  than 
ratun  Trua; 

•laa 

if  Right. Valua  >“  To_SQL_Dacimal_Not_Null (Lowar)  and  than 
Right. Valua  <«  To_SQL_Dacimal_Not_Null (Uppar)  than 
return  Trua; 

•laa 

return  Falaa; 
and  if; 
and  if; 

and  Is_In_B*aa ; 

function  Ia_Null (Valua  :  SQL  Dacimal)  raturn  boolaan  ia 
bagin 

raturn  Valua . Is_Null ; 
and  la  Null; 

function  Not_Null (Valua  :  SQL_Dacimal)  raturn  boolaan  ia 
bagin 

raturn  not  Valua . Ia_Null ; 
and  Not_Null; 

function  ”+"  (Right  :  SQL_Dacimal  Not_Null)  raturn  SQL_Dacimal_Not_Null  ia 
bagin 

raturn  Right ; 
and  "+”; 

function  "+"  (Right  ;  SQL_Dacimal)  raturn  SQL_D*cimal  ia 
bagin 

raturn  Right; 

and 

function  (Right  :  SQL_Dacimal_Not  Null)  raturn  SQL  Dacimal_Not_Null  ia 

Valua  :  Mar  Dacimal; 
bagin 

invaraa  (Valua,  Right .Valua) ; 
raturn  (Right . Seal*,  Valua); 
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•nd 


function  (Right  :  SQL_Dacimal)  raturn  SQL  Dtcuul  ra 

bagin 

if  Right . Ia_Null  than 

raturn  Nuil_SQL_Dac i  mal ; 

alaa 

raturn  (Right . acala,  Falaa,  - (Right . Valua) ) ; 
and  if ; 

and 

function  "aba"  (Right  :  SQL_Dacimal_Not_Hull)  raturn  SQL_Daeimal_Hot_Uull  ia 
Valua  :  Max_Dacimal ; 
bagin 

abav  (Valua,  Right .Valua) ; 
raturn  (Right . Scala,  Valua); 
and  "aba"; 

function  "aba"  (Right  :  SQL  Dacimal)  raturn  SQL  Dacimal  ia 
bagin 

if  Right . Ia_Null  than 

raturn  Null_SQL  Dacimal; 

alaa 

raturn  (Right . acala,  Falaa,  aba (Right. Valua) ) ; 
and  if ; 
and  "aba"; 

function  "+"  (Laft,  Right  :  SQL_Dacimal_Not_Null) 
raturn  SQL_Dacimal_Not_Null  ia 
diga  ;  intagar; 

Raault,  Holdar  :  SQL_Dacimal_Hot_Null; 
arror  :  boolaan  :=  falaa; 
bagin 

if  l4af  t .  acala  /=  Right,  acala  than 

diga  : =  aba (intagar (Laft .acala  -  Right . acala) ) ; 
if  Laft . acala  >  Right . acala  than 
Holdar  :a  Right; 

add  (Raault . Valua ,  Laft. Valua,  Shift (Holdar,  diga) .Valua, 
arror) ; 

alaa 

Holdar  : «=  Laft; 

add  (Raault . Valua ,  Shift (Holdar,  diga) .Valua,  Right. Valua, 
arror) ; 

and  if; 

alaa 

add  (Raault. Valua,  Laft. Valua,  Right. Valua,  arror) ; 
and  if ; 
if  arror  than 

raiaa  Conntraint_Error ; 

alaa 

raturn  (max (Laft . acala, Right . acala) ,  Raault. Valua ) ; 
and  if; 
and  "+"; 

function  ”+”  (Laft,  Right  :  SQL_Dacimal) 
raturn  SQL_Dacimal  ia 
bagin 

if  Laft . Za_Null  or  alaa  Right . Za_Hull  than 
raturn  Hull  SQL  Dacimal; 

alaa 

raturn  (max (Laft . acala ,  Right . acala) ,  Falaa, 

(Laft .Valua  +  Right .Valua) ) ; 

and  if; 
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and  " + ” ; 

function  (Laft,  Right  :  SQL_Dacimal_Not_Null) 

ratum  SQL_Dacimal_Not_Null  ia 
digs  intagar; 

Raault,  Boldar  :  SQL_Dacimal_Not_Null; 
arcor  :  boolaan  :=  falsa; 
bagin 

if  Laft . acala  /=  Right . icala  than 

diga  : “  aba (intagar (Laft . acala  -  Right . acala )) ; 
if  Laft . acala  >  Right . acala  than 
Boldar  : as  Right; 

aub tract  (Raault .Valua,  Laft .Valua,  Shift (Boldar ,  diga) .Valua, 
arror) ; 

alaa 

Boldar  : =  Laft; 

aubtract  (Raault .Valua,  Shift (Boldar ,  diga) .Valua, 

Right. Valua,  arror); 

and  if; 

alaa 

aubtract  (Raault .Valua,  Laft. Valua,  Right. Valua,  arror); 
and  if; 
if  arror  than 

raiaa  Conatr aint_Error ; 

alaa 

ratum  (max (Laft .acala,  Right . acala) ,  Raault .Valua) ; 
and  if ; 

and 

function  (Laft,  Right  :  SQL_Dacimal) 

ratum  SQL_Dacimal  ia 
bagin 

if  Laft.Ia_Mull  or  alaa  Right . Ie_Hull  than 
ratum  Null_SQL_Dacimal; 

alaa 

ratum  (max (Laft. acala,  Right. acala) ,  Falaa, 

(Laft. Valua  -  Right . Valua )) ; 

and  if; 

and 

function  (Laft,  Right  :  SQL_Dacimal_Not_Null) 

ratum  SQL_Dacimal_Not_Null  ia 
Raault  :  SQL_Dacimal_Not_Null ; 
arror  :  boolaan  :=  falaa; 
bagin 

if  (Laft  a  Zaro)  than 
ratum  Laft; 

alaif  (Right  a  Zaro)  than 
ratum  Right; 
and  if; 

if  (Laft. acala  4  Right. acala)  >  dacimal_digita ' laat  than 
raiaa  Conatraint  Error; 
and  if; 

multiply  (Raault .Valua,  Laft. Valua,  Right. Valua,  arror); 
if  arror  than 

raiaa  Conatraint_Error ; 
and  if; 

ratum  ((Laft.  acala  4  Right .  acala)  ,  Raault  .Valua)  ; 

and 

function  (Laft,  Right  :  SQL_Dacimal) 

ratum  SQL_Dacimal  ia 
bagin 
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if  Left.Is_Null  or  else  Right . Ia_Null  than 
return  Null_SQL_Decimal; 

•la* 

if  L«ft.V«lu*  *=  Z«ro  then 
return  Left; 

elaif  Right. Value  *  Zero  then 
return  Right; 

•lae 

return  ((Left.aoale  +  Right . acale) ,  Falae, 

(Left. Value  *  Right . Value) ) ; 

end  if; 
end  if; 
end  ; 

function  "/"  (Left,  Right  :  SQL_Decimal_Not_Hull ) 
return  SQL  Decline  I _Not_Null  ia 

prec  :  decimal  digit*  : =  decimal  digit* (decimal  digit* ' laat) ; 
Left_diga,  Right_diga,  Re*ult_dig*  :  integer ; 

Right_Scale,  Reault_Scale  :  integer; 

Right_Holder ,  Reault  Bolder  ;  SQL_Decimal_Not_Null; 
error  :  boolean  :=  falae, 
begin 

if  (Left  *=  Zero)  then 
return  Left; 
end  if; 

Right_Bolder  :*  Right; 

—  shift  the  BCD  value  in  Right_Holder  all  the  way  to  the 

right,  eliminating  trailing  zeroes 

—  adjust  the  scale  accordingly 

—  this  will  help  to  yield  a  reault  of  maximum  precision 

trailing_zeroes  (Right_Holder .Value,  prec,  Right_diga) ; 
if  Right_diga  *=  decimal_digita ' last  then 
raise  Constraint_Error; 

else 

Right_digs  :  «=  -Right_digs; 

Right_Holder  :■>  Shift  (Right_Bolder ,  Right_digs) ; 
Right_acale  :■  Right. scale  +  Right_digs; 
end  if; 

—  perform  divide  operation 

divide  (Result_Bolder .Value,  Left . Value, 

Right_Bolder .Value,  Left_digs,  error); 

if  error  then 

raise  Constraint_Error; 

end  if;  * 

—  if  the  scale  of  the  result  is  outside  the  bounds  of 

—  the  available  precision,  shift  the  result  left  or 
right ,  accordingly 

Result_scale  : “  Left. scale  -  Right_scale  +  Left_digs; 
if  Reault_scale  >  decimal_digits ' last  then 

Result_digs  : “  decimal  digits'  last  -  Result_scale; 
Result_acale  :«  decimal  digits' last; 

Result_Bolder  :»  Shift  (Result_Bolder,  Result_digs) ; 
elsif  Reault_Sc*le  <  0  then 

Result_Bolder  :*  Shift  (Result_Bolder,  abs (Result_Scale) ) ; 
Result_Scale  ; “  0; 
end  if ; 
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return  (decimal_digita (Reault_acale) ,  Reault_Holdar . Value)  ; 

and 

function  "/"  (Left,  Right  SQL_De cimjl) 

return  SQL_Decimal  ia 
begin 

if  Left.la_Null  or  alee  Right . Ie_Null  then 
return  Null_SQL_Decimal; 

alee 

return  ("/" (Left .Value,  Right . Value) . scale,  Falae, 

(Left. Value  /  Right . Value )) ; 

end  if; 

end 

function  "*■  (Left  :  SQL_Decimal_Not_Hull ;  Right  :  SQL_Int_Not_Null) 
return  SQL  Deci2nal_Not_Null  ia 
begin 

return  (Left  *  To_SQL_De c ima 1_N ot_N all (Right) ) ; 

end 

function  (Left  ;  SQL_Deeimal;  Right  :  SQL_Int_Not_Null) 

return  SQL_Decimal  ia 
begin 

if  Left . Ia_Null  then 

return  Null_SQL_Decimal; 

alee 

return  (Left.acale,  Falae,  (Left. Value  *  Right)); 
end  if; 

end 

function  (Left  :  SQL_Decimal;  Right  :  SQL_Int) 

return  SQL_Decimal  ia 
begin 

if  Left . Ia_Null  or  elae  Ia_Null (Right)  then 
return  Null_SQL_Decitnal; 

elae 

return  (Left.acale,  Falae, 

(Left. Value  *  Without_Null_Baae (Right) )) ; 

end  if; 
end  " * ” ; 

function  (Left  :  SQL_Int_Not_Null;  Right  :  SQL  Decimal_Not_Null) 

return  SQL_Decimal_N ot_Nul  1  ia 
begin 

return  (To  SQL_Deciaal_Not_Null (left)  *  Right); 

end 

function  (Left  :  SQL_Int_Not_Null;  Right  :  SQL_Decimal) 

return  SQL_Decimal  ia  , 

begin 

if  Right . Xe_Null  then 

return  Hull  SQL_Decimal; 

elae 

return  (Right . acale,  Falae,  (Left  *  Right. Value) ) ; 
end  if; 
end  ” * " ; 

function  (Left  :  SQL_Int;  Right  :  SQL_Decimal) 

return  SQL__Oecimal  ia 
begin 

if  Right .Ia_Null  or  elae  Xe_Hull (Left)  then 
return  Null  SQL  Decimal; 

elae 
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return  (Right . seel* ,  False, 

(Without  Null_Base (Left)  *  Right .Value) ) ; 

end  i£ ; 
end  " * "  ; 

function  "/"  (Left  :  SQL_Decimal_Not_Null;  Right  :  SQL_Int_Not_Null ) 
return  SQL_Deeimal  Not_Null  ia 
begin 

return  (Left  /  To_SQL_Decimel_Not_Null (Right )) ; 

end 

function  "/"  (Left  :  SQL_Dec irnal ;  Right  :  SQL_Xnt  Not_Hull ) 
return  SQL  Decimal  ia 
begin 

if  Left.Is_Null  then 

return  Null_SQL_Decimal; 

elae 

return  ("/" (Left .Value,  Right) . scale ,  False, 

(Left .Value  /  Right) ) ; 

end  if; 

end 

function  "/"  (Left  :  SQL_Decimal ;  Right  ;  SQL_lnt) 
return  SQL  Decimal  is 
begin 

if  Le£t.Is_Null  or  elae  la_Null  (Right)  then 
return  Null_SQL_Deeimal; 

else 

return  ("/" (Left .Value,  Without_Null_Baae (Right) ). scale, 

False,  (Left .Value  /  Without_Null_Base (Right) )) ; 

end  if; 

end 

function  To_SQL_Decimal_Not_Null  (Right  :  SQL_Int_Not_Null ) 
return  S QL_D ec imal_N ot_N ul 1  is 
Bolder  :  SQL_Decimal_Not  Null; 
begin 

integer_to_decimal (Holder .Value,  BCD_Int_Type (Right) ) ; 
return  Bolder; 

end  To_SQL_Decimal_Not_Null; 

function  T o_SQL_De cima 1_N o t_N u 11  (Right  :  SQL_Double_Precision_Not_Null) 
return  SQL_Decimal_Not_Null  is 
Value  :  Max_Decimal; 

Scale  :  dec imal _digits ; 

prec  :  integer  : *=  SQL_Double_Precision_Not_Null' digits; 
exp  :  integer; 

tenp_string  :  string (1 . .prec+6) ; 

Number_String  :  SQL_Char_Not_Null (1 . . decimal_digits' last+1)  := 

(1  E>  2 .. decimal_digita ' last+1  =>  ' 0' ) ; 

begin 

put (to  =>  temp_string, 
item  =>  Right, 
aft  *>  prec  -  1, 

•*P  =>  3) ; 

exp  : “  integer ' value (temfi  string (prec+4 . .prec+6) ) ; 
tenp_string(3 .  .prec+1)  teoy_string (4  .  .prec+2)  ; 
if  exp  <  prec-1  then 

if  exp-prec+1  <  - (decimal_digits  last)  then 
raise  Constraint_Erxor ; 

else 

Scale  : «=  abs  (exp  -  (prec  -  1)); 
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Nuiob*r_String (d*cim*l_digita ' l**t+2-pr*c. . 

d*cim*l_digita ' la*t+l)  := 
To_SQL_Ch*r_Not_Null (tamp_atring (2 . . pr*c+l ) ) ; 

•nd  if ; 

•la* 

if  axp  >  dacimal  digit*' la*t-l  than 
raiaa  Con*tr*int_Error ; 

ala* 

Sc*.la  : =  0; 

Nunbar_String(dacimal_digita' iaat+l-axp. . 

dacimal_digita '  laat-axp+prac)  : «= 
To_SQL_Char_Not_Null (tamp_atring (2 . . prao+1) ) ; 

and  if; 
and  if; 

if  t*mp_*tring ( 1 )  *  '  - '  than 
Humb*r_String (1)  := 

and  if; 

numaric_atring_to_dacim*l  (Valua,  Numb*r_String) ; 
ratuis  (Seal*,  Valua) ; 
and  To_SQL_D*cim*l_Not  Null; 

function  To_SQL_D*cimal_Not_Null  (Right  :  SQL_Char_Not_Null ) 
ratum  SQL_D*cimal_Not_Null  ia 

tamp  :  SQL_Ch*r_Not_Null (1 . . dacimal_digita' laat+1) ; 
frat,  lat,  indx,  lngth  :  intagar; 

tamp _ Beil*  :  dacimal  digit*  : =  0; 

dacimal_f ound  :  boolaan  : *=  falaa; 

Valua  :  Max_D*cimal ; 
bagin 

lat  : =  Right' langth; 

if  Right (1)  =  or  alaa  Right (1)  *  ' +'  than 

tanp ( 1 )  :=  Right ( 1 ) ; 

frat  : =  2; 

•laif  Right  (1)  =  '  '  than 

tamp (1)  :=  '  +'  ; 

frat  :*  2; 

alaa 

t*i^>(l)  :«  '+'; 

frat  :■  1; 
and  if; 
lngth  :«  1; 

for  indx  in  frat . . lat  loop 
lngth  :  =  lngth  +  1; 
if  Right (indx)  a  ' than 
if  dac ima 1 _£ ound  than 

raiaa  Conatraint_Error ; 

alaa 

dacimal _ found  :  *=  trua; 

t*mp_*cal*  : «=  d*cimal_digita (lat  -  indx); 
lngth  :*  lngth  -  1 ; 
and  if; 


alaif  ( (Right (indx) 

= 

'0'  ) 

or 

alaa 

(Right (indx) 

s 

'1') 

or 

alaa 

(Right (indx) 

a 

'2' ) 

or 

ala* 

(Right (indx) 

a 

'3') 

or 

ala* 

(Right (indx) 

= 

'4') 

or 

alaa 

(Right (indx) 

■ 

'5') 

or 

alaa 

(Right (indx) 

m 

'6') 

or 

ala* 

(Right ( indx) 

= 

'7') 

or 

ala* 

(Right (indx) 

E 

'  8' ) 

or 

ala* 

(Right (indx) 

a 

'»’)) 

than 

tamp  (lngth)  :  «=  Right  (indx)  ; 

ala* 
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raisa  Con*tr»int_Error ; 
and  if; 
and  loop ; 

if  lngth  <  dacimal_digits '  laat+1  than 

tanp  :=  tanp(l..l)  &  (2 . . dacimal_digita' last+2-lngth  =>  '0')  t 

t asp  (2 . . lngth) ; 

and  if; 

numarxc _ at ring _ to^dacinal  (Valua,  tanp) ; 

ratum  (tasp_acala,  Valua)  ; 
and  To_SQL_Dac imal_N ot_Nul 1 ; 

function  To_SQL_Dscimal  (Right  :  SQL  Int_Not_Null)  raturn  SQL_Dacimal  is 
bagin 

ratum  (0,  Falsa,  To_SQL_Dacimal_Kot_Hull  (Right)  )  ; 
and  To_SQL_Dacimal  ; 

function  To_SQL_Dacimal  (Right  :  SQL_lnt)  raturn  SQL_Dacimal  is 
bagin 

if  ls_Null (Right)  than 

ratum  Mull_SQL  Dacimal; 

alsa 

ratum  (0,  Falsa,  To_SQL_Dacimal_Not_Null ( 

Without  Kull_Basa (Right) ) ) ; 

and  if ; 

and  To_SQL_Dacimal  ; 

function  To_SQL_Dacimal  (Right  :  SQL_Doubla_Praciaion_Not_Null) 
ratum  SQL_Dacimal  is 
bagin 

ratum  (To_SQL_Dacimal_Not_Null (Right) . scala,  Falsa, 
To_SQL_Dacimal_Not_Null  (Right)  )  ; 
and  To_SQL_Dacimal ; 

function  To_SQL_Daeimal  (Right  :  SQL_Doubla_Pracision)  raturn  SQL_Dacimal  is 
bagin 

if  Is_Null (Right)  than 

ratum  Null_SQL_Daci  mal  ; 

alsa 

ratum  (To_SQL_Dacimal_Not_Null (Without_Null_Basa (Right) ) .scala, 

Falsa,  To_SQL_Dacimal_Not_Null  (Withe  jt_Null_Basa  (Right)  )  )  ; 

and  if; 

and  To  SQL_Dacimal ; 

function  To_SQL_Dacimal  (Right  :  SQL_Char_Not_Null) 
ratum  SQL_Oacimal  is 
bagin 

ratum  (To_SQL_Dacimal_Not_Null  (Right)  .  scala,  Falsa, 
To_SQL_Dacimal_Not_Null (Right) ) ; 
and  To  SQL_Dac ima 1 ; 

function  To_SQL_Dacimal  (Right  :  SQL_Char) 
ratum  SQL_Dacimal  is 
bagin 

if  Is_Null (Right)  than 

ratum  Hull  SQL  Dacimal; 

alsa 

ratum  (To_SQL_Dacimal__Not_Null  (Without_Hull_Basa  (Right)  )  .scala, 

Falsa,  To_SQL_Dacimal_Not_Null (Without_Null_Basa (Right) ) ) ; 

and  if ; 

and  To_SQL_Dacimal ; 

procadura  Aasign_To_SQL_Dacimal  (bound  :  in  out  SQL  Dacimal_Hot  Null2; 

sign  :  Sign_Charactar ; 
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Integral,  a cal*  :  Nuraeric_String; 

In  scale  :  decimal  dr gits)  Is 

subtype  new  char  is  SQL  f.har  Not_Null  (1 ..  integral '  length+scale  '  length)  ; 
Length  Integer  :=  integral ' length  +  scale' length; 

Number  String  :  SQL_Char_Not_Null (1 ■■ Length+2) ; 

function  line  is  new  unchec)ced_conversion  (source  *=>  Numeric_String, 

target  c>  new  char) ; 


begin 

if  Length  >  decimal  digits 'last  then 
raise  Constraint_Error ; 
end  if ; 

Number_String  : «  unc (integral  4  scale)  4  "00"; 
if  sign  *  then 

Number_String(l . .Length+2)  :*  4 

Number_String (1 . . Length -in_scale)  4 
"  4 

Number  String (Length- in_scale+l . . Length) ; 

else 

Number_String (1 . .Length+2)  :«  "+"  4 

Number  String (1 . . Length-in_scale)  4 

"  ,  "  4 


Number  String (Length- in_scale+l . .Length) ; 

end  if; 

bound  : =  To  SQL  Decimal_Not_Null2 ( 

To  SQL  Decimal_Not_Null (Number_String)  ) ; 
end  Assign_To_SQL_Decimal; 


function  To_SQL_Int_Not_Null  (Right  :  SQL_Decimal_Not_Null) 
return  SQL_Int_Not_Null  is 
Bolder  :  BCD_Int_Type ; 

Decimal_Holder  :  SQL_Decimal_Not_Null ; 
error  :  boolean  :*  false; 
begin 

if  Right . scale  >  0  then 

Decimal_Holder  - *=  Right; 

decimal  to_integer (Bolder ,  Shift  (Decimal_Holder, 

-integer (Right . Scale) ) .Value,  error) ; 

else 

decimal_to_integer (Holder,  Right. Value,  error); 
end  if ; 
if  error  then 

raise  Constraint_Error ; 

else 

return  SQL  Int_Not_Null (Bolder) ; 
end  if; 

end  To  SQL  Int  Not  Null; 


function  To_SQL_Int_Not_Null  (Right  ;  SQL _ Decimal) 

return  SQL_Int_Not_Null  is 
begin 

if  Right . Xs_Null  then 

raise  Null__Value_Error ; 

else 

return  To_SQL  Int_Not_Null (Right .Value) ; 
end  if; 

end  To  SQL  Znt  Not  Null; 


function  To  SQL_Int  (Right  :  SQL_Decimal) 
return  SQi>_Int  is 
begin 

if  Right . ls_Null  then 

return  Null_SQL_Int; 

else 
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r*tum  With_Null_Baaa (To_SQL_Int_Not_Null (Right . Value) ) ; 
and  if ; 

and  To  SQL_Int  ; 

function  To_SQL_Double_Pracision_Not_Null  (Right  SQL_Decimal_Not_Null) 
ratura  SQL_Double_Precision_Not_Null  ia 
indx,  lngth  :  integer; 

Number_String  :  SQL_Char_Not_Null  (1.  . dacimal_digits'  laat-t-1 )  ; 
tamp_holdar  :  intagar; 

prac  :  intagar  :=  SQL_Doubla_Preciaion_Not  Null 'digits; 
bagin 

dacimal_to_numeric_atring  (Number_String,  Right .Value) ; 
indx  : *  2  ; 

while  ((indx  <  decimal_digits' laat+2)  and  than 
(Number_String (indx)  =  '0'))  loop 
indx  :  =  indx  +  1; 
and  loop ; 

if  indx  =  dacimal_digita' laat+2  than 
ratum  0.0; 
and  if; 

if  indx  <  dacimal_digita' last+3-prec  than 

tamp_holdar  :=  integer ' value (To_String (Number  String ( 
indx . . indx+prac-1) ) ) ; 
lngth  :=  prec-1; 

alaa 

teiq>_holdar  :=  intagar' value (To_String (Numbar  String ( 
indx. . dacimal_digita '  laat+1) ) ) ; 
lngth  :=  dacimal_digita' laat+l-indx; 
and  if; 

if  Numbar_String (1)  =  than 

tamp_holdar  :=  -tamp  holder; 
and  if ; 

if  Rig*  t  Scala  *  0  than 

return  (SQL_Doubla_Praciaion_Not_Null (temp_holder )  *  (10.0  **  ( 

dacimal_digita ' last  +  1  -  indx  -  lngth))); 

alaa 

return  (SQL_Double_Precision_Not_Null (tamp_holder)  *  (10.0  ** 

(decimal_digita' last  +  1  -  indx  -  lngth  -  integer (Right . scale) ))) ; 
and  if; 

and  To_SQL_Double_Precision_Not  Null; 

function  To_SQL_Double_Precisiar._Not  Null  (Right  :  SQL_Decimal) 
ratum  SQL_Double_Precision  Not  Nall  ia 
bagin 

if  Right . Ia_Null  than 

raiaa  Null_Valua_Error ; 

alaa 

ratum  To_SQL_Double_Preciaion  Not_Null (Right . Value) ; 
and  if; 

and  To_SQL_Double_Precision_Not  Null; 

function  To_SQL_Double_Precision  (Right  SQL  Decimal) 
return  SQL  Double_Precision  is 
bagin 

if  Right . Is_Null  than 

return  Null_SQL_Double  Precision; 

else 

return  With_Null_Baaa (To_SQL_Doubla  Praciaion_Not_Null  ( 

Right. Valua) ) ; 

and  if; 

and  To_SQL_Doubla_Praciaion; 

function  To_String  (Right  SQL_Dacimal_Not  Null)  return  string  is 
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Holder  SQL_Cher_Not_Null ( 1 . . d»cimel_digite ' last +3 ) ; 
xridjc  integer; 
begin 

decimel_to_numeric_etring  (Holder,  Right . Value ) ; 
if  Holder (1)  =  ' +'  then 
Holder (1)  :=  '  '; 

end  if ; 

if  Right . ecele  >  0  then 

Holder ( dec i m»l_digit« '  l*et+3 -Right . ecele .  . 
decimel_digite' leet+2)  := 

Holder (decimel_digite'  leet+2-Right .ecele . . 
decimel_digite ' leet+1) ; 

Holder (decimel_digite' leet+2-Right . ecele)  := 

Holder (3 .. decimel_digite ' leet+3)  := 

Holder (2 . . decimel_digite ' leet+2) ; 

Holder (2)  :=  'O'; 

indx  :  =  2  ; 

while  (Holder (indx)  =  '0')  loop 
indr  : =  indx  +  1 ; 
end  loop ; 

if  Holder (indx)  =  '  .'  then 
indx  : —  indx  -  1 ; 
end  if; 

return  To_String (Holder (1 .. 1)  £ 

Holder (indx. . decimel_digite ' leet+3) ) ; 

elee 

indx  : =  2  ; 

while  (Holder (indx)  =  '0'  end  then 

indx  <  decimel_digite' leet+2)  loop 
indx  :=  mdx  +  1; 
end  loop ; 

if  indx  =  decimel_digite ' laet+2  then 
return  "  0 " ; 

elee 

return  To_String (Holder (1 .. 1 )  t 

Holder (indx. . decimel_digite' leet+1) ) ; 

end  if ; 
end  if; 

end  To  String; 

function  To _ String  (Right  :  SQL._Decr.Tel)  return  etring  ie 

begin 

if  Right . Ie_Null  then 

reiee  Null_Velue_Error; 

elee 

return  To_String (Right . Velue) ; 
end  if ; 

end  To_String; 

function  To_SQL_Cher_Not_Null  (Right  :  SQL_Decimal_Not_Null) 
return  SQL_Cher_Not  Null  ie 

Holder  SQL_Cher_Not_Null (1 . . decimel_dr gite ' leet+3) ; 
indx  integer ; 

begin 

decimel_to_numeric_etring  (Holder,  Right .Velue) ; 
if  Holder (1)  =  '+'  then 
Holder (1 )  :=  '  ' ; 

end  if; 

if  Right. ecele  >  0  then 

Holder (decimel_digite ' leet : 2  Right . ecele  .  . 
decimel_digite' leet+2) 

Holder (decimel_digite '  leet+2 -Right . ecele .  . 
decimel  digite' leet+1); 
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I  nlder  (decuael^digit#  l«»t  »2  Right  acal#  J  » 
loldu(3  .  4«cuul_digUi  lutt3|  » 

Hold#c(2  daciul  digit#  luu2) 

Holder (2 )  «  0 

in  dr  :  ■  2 

while  (Holder ( Lndi)  ■  O')  loop 

in  dr  : m  in  dr  *  1 
end  loop . 

it  Bolder ( indx)  »  tben 

in  dr  .  ■  in  dr  -  1 . 
end  if; 

ret  urn  Holder  (1  .  .  1)  4  Bolder!  indx  .  .  decimal  digit#'  leetO) 

elee 

indx  : e  2: 

while  (Bolder ( mdx)  ■  'O’  end  then 

indx  <  decieel_diglte  leet*2)  loop 
indx  : •  indx  ♦  1 . 
end  loop ; 

if  indx  ■  d#cim*l_digit# '  l##t  +  2  then 
return  "  0" 

elee 

return  Holder (1..1)  4  Bolder (indx .. dec leal  digit#  la#t*S) 
end  if; 
end  if ; 

end  To_SQL_Char_Not_Null ; 

function  To_SCL_Chrr_Hot  Null  (Right  :  SQl,_Decu#el ) 
return  SQL_Ch#r_Not_Nu 1 1  re 
begin 

if  Right . le_Null  then 

reiae  Null_Velue_Error ; 

elee 

return  To_SQL_Char_Not_Null (Right . V  je) ; 
end  if ; 

end  To_SQL_Ch*r_Not_Null ; 

function  To_SQL_Char  (Right  :  SQl  J>e c ime  1 ) 
return  SQL_Char  ia 
begin 

if  Right. Ie_Null  then 

return  Null_SQL_Char ; 

elae 

return  With_Null_Baae (To_SQL_Char_Not_Null (Right .Value) ) ; 
end  if; 

end  To_SQL_Char; 

function  Width  (Right  :  SQL_Decimal_Not_Null)  return  integer  ia 

begin 

return  To_SQL_Char_Not_Null (Right) ' length; 
end  Width; 

f unction  Width  (Right  :  SQL_Dec ima 1 )  return  integer  ia 

begin 

if  Right . Ia_Null  then 

raiae  Null_Value_Error ; 

elae 

return  Width  (Right . Value ) ; 
end  if ; 
end  Width; 

function  Integral_Digita  (Right  :  SQL_Decimal_Not_Null ) 
return  decimal  digita  ia 
begin 
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return  decimal_digita  (decxmal_di.gi.ta'  laat- integer  (Right,  acele)  )  ; 
end  lntagral_Digita; 

f unction  Integral  Digita  (Right  :  SQL  Decimal) 
return  decimal _digita  ia 
begin 

return  Integral_Digita (Right . Value ) ; 
end  Integral_Digita; 

£ unction  Scale  (Right  :  SQL_Decimal_Not_Null) 
return  decimal  digita  ia 
begin 

return  Right . a  sale ; 
end  Scale; 

function  Scale  (Right  :  SQL_Decimal) 
return  decimal_digita  ia 
begin 

return  Scale (Right . Value ) ; 
end  Scale ; 

function  Fore  (Right  :  SQL_Decimal_Not_Null) 
return  poaitive  ia 
integral,  dig a  ;  integer; 
begin 

integral  ; «•  deciaal_digita '  laat- integer (Right . Scale) ; 
leading_zeroea  (Right .Value,  integral,  diga) ; 
diga  : ■  integral  -  diga; 
if  diga  e  0  then 
return  1; 

elee 

return  poaitive <  diga ) ; 
end  if ; 
end  Fore; 

function  Fore  (Right  :  SQL_Deoimal)  return  poaitive  la 
begin 

if  Right . Ie_Null  then 

raiee  Hull_Value_*rror; 
end  if; 

return  For a (Right . Value) ; 
end  Fore; 

function  Aft  (Right  :  SQL_Decimal_Not_Hull )  return  poaitive  ia 
diga  :  integer; 
begin 

if  Right . Scale  «  0  then 
return  1 ; 

elae 

trailing_zeroea  (Right .Value ,  Right. Scale,  diga) ; 
diga  : “  integer (Right . Scale)  -  diga; 
if  diga  *  0  then 
return  1; 

elae 

return  poaitive (diga) ; 
end  if; 
end  if; 
end  Aft; 

function  Aft  (Right  :  SQL_Decimal)  return  poaitive  ia 
begin 

if  Right . Ia_Hull  then 

raiae  Mull  Value  Error; 
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end  if ; 

return  Aft (Right .Value) ; 
end  Aft; 

function  Machine  Rounds  (Right  SQL  Decimal  Hot  Hull) 
return  boolean  is 
begin 

return  True ; 
end  Machine _ Rounds ; 

function  Machine  Rounds  (Right  :  SQL  Decimal) 
return  boolean  is 
begin 

return  True; 
end  Machine _ Rounds ; 

function  Machine_Over flows  (Right  :  SQL  Decimal  Hot  Hull) 
return  boolean  is 
begin 

return  True; 
end  Machine  Overflows; 

function  Machine  Overflows  (Right  ;  SQL  Decimal) 
return  boolean  is 
begin 

return  True; 
end  Machine_Overf lows  ; 

package  body  SQL_Decimal_Ops  is 

lower_bound  :  SQL_Decimal_Hot_Hull2 (in_ecale) ; 
upper_bound  :  SQL_Decimal_Hot_Hull2 (in_scale) ; 

procedure  Assign  (Left  :  in  out  Without_Null_Type; 

Right  :  Without_Null_Type)  is 

begin 

Assign_with_check  (Left,  Right,  lower_bound,  upper_bound) 
end  Assign ; 

procedure  Assign  (Left  :  in  out  With_Hull_Type; 

Right  :  With_Hull_Type )  is 

begin 

Assign_with_check  (Left,  Right,  lower_bound,  upper_bound) 
end  Assign; 

function  Is_In  (Right  :  Without_Hull  Type) 
return  boolean  is 
begin 

return  Is_In_Baae (Right,  lower  bound,  upper  bound); 
end  Is  In; 

function  Is_In  (Right  :  With_Hull_Type) 
return  boolean  is 
begin 

return  Is_In_Base (Right,  lower_bound,  upper_bound) ; 
end  Is  In; 

function  Vfith_Hull  (Value  :  Without_Hull_Type) 
return  With_Null_Type  is 
begin 

return  To_SQL_Decimal (To_SQL_Decimal_Hot_Hull2 (Value) ) ; 
end  With  Hull; 
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function  Without  Null  (Valua  :  With  Null_Typa) 
raturo  Without  Null_Typa  ia 
bagin 

rttum  To_SQL_Dacimal_Not_Null  (To_SQL_Dacimal_Not_Null2  (Valua)  )  , 
and  Without  Null; 


bagin 

Aaaign_To_SQL_Dacimal  (loaar_bound,  fizat_aign,  f  irat_intagral, 

firat_fractional,  in  acala) ; 

Aaaign_To_SQL_Dacimal (uppar_bound,  laat_aign,  laat_intagral, 

laat_fr actional,  in_acala) ; 

and  SQL_Dacimal_Opa ; 
and  SQL_Dacimal_Pkg; 


C.20  SQLDecimal  Assembler  Support  (VAX) 


PROCEDURE  I2D 

procadura  intagar_to_dacixnal  (Valua  :  in  out  Max_Dacimal  ; 

Right  :  intagar) ; 

—  thia  procadura  convarts  an  intagar  into  a  packad  dacimal 

—  numbar  31  digita  long 


.PSECT  12D 

•ENTRY  I 2D  *M<R2,  R3> 
CVTLP  @8(AP),#31,84(AP) 
RET 
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;  —  this  procedure  convarti  a  numeric  string  of  31  digits  and  a 
;  —  sign  from  leading  separate  numeric  format  into  a  packed 
;  --  decimal  number  of  31  digits 


.PSECT  NS2D 

•  ENTRY  NS2D  AM<R2,  R3> 

CVTSP  #31,08 (AP ) , #31, @4 (AP ) 
RET 


PROCEDURE  D2NS 

* 

;  procedure  decimal_to_numeric_string  (Value  :  in  out  string; 

;  Right  :  Max_Decimal ) ; 

;  —  this  procedure  converts  a  packed  decimal  number  of  31  digit 
;  —  into  a  numeric  string  in  leading  separate  numeric  format 


•PSECT  D2NS 

•  ENTRY  D2NS  AM<R2,  R3> 

CVTPS  #31,68 (AP) ,#31,@4 (AP) 
RET 


PROCEDURE  LZ 

procedure  leading_zeroes  (Value  :  Max_Decimal; 

integ  :  integer; 

digs  :  in  out  integer) ; 

—  this  procedti re  returns  the  number  of  leading  zeroes  in  the 

—  first  "integ"  digits  of  the  packed  decimal  number 


LOOP: 


DONE: 
DONE3 : 


•PSECT  LZ 

•  ENTRY  LZ  AM<R2,  R3,  R4,  RS,  RS,  R7,  R8> 


MOVL 

08  (AP)  ,  R4 

MOVL 

4(AP),R5 

CLRL 

R8 

IN  CL 

R8 

MOVB 

(R5)  ,  R6 

BICL3 

# AXFFFFFFOF , R6 , R7 

CMPB 

#AX00,R7 

BNEQ 

DONE 

DECL 

R4 

CMPB 

#AX00,R4 

BEQL 

DONE3 

IN CL 

R8 

BICL3 

#AXFFFFFFFO , R6, R7 

CMPB 

#AX00,R7 

BNEQ 

DONE 

DECL 

R4 

CMPB 

#AX00,R4 

BEQL 

DONE3 

IN  CL 

R5 

BRB 

LOOP 

DECL 

R8 

MOVL 

RET 

R8, 012 (AP) 
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PROCEDURE  TZ 

procadura  trailing  zaroas  (Valua  :  Max_Dacimal ; 

seal  :  daciraal_digits; 
digs  :  in  out  intagar) ; 

—  this  procadura  ratums  tha  mimhar  of  trailing  zaroas  in 

—  tha  last  "seal”  digits  of  tha  packad  dacimal  numbar 


* 

.PSECT 

TZ 

■ENTRY 

TZ  AM<R2,  R3,  R4,  R5,  R6,  R7,  R8> 

MOVL 

08 (AP) ,  R4 

MOVL 

4  (AP)  ,  R5 

ADDL 

#15, RS 

MOVB 

(R5),R6 

CLKL 

R8 

LOOP1 : 

IN  CL 

R8 

BICL3 

#''XFFFFST0F ,  R6,  R7 

CMPB 

#AX00,R7 

BNEQ 

DONE1 

DECL 

R4 

CMPB 

#/'X00,R4 

BEQL 

DONE2 

DECL 

R 5 

MOVB 

(R5),R6 

IN  CL 

R8 

BICL3 

#,'XFFFFFFFO ,  R6 ,  R7 

CMPB 

#-'X00,R7 

BNEQ 

DONE1 

DECT 

R4 

CMPB 

#AX00,R4 

BEQL 

DONE2 

BRB 

LOOP1 

DONE1: 

DECL 

R8 

DONE 2 : 

MOVL 

RET 

R8, @12 (AP) 

/ 

;  PROCEDURE  INV 

;  prooadura  invarsa  (Valua  :  in  out  Max  Dacimal; 

/ 

Right  :  Max_Dacimal) ; 

;  —  this  procadura  ratums  tha  invarsa  of  Right  in  Valua 

r 

t 

■PSECT 

INV 

■ENTRY 

INV  AM<R2,  R3,  R4> 

MOVC3 

#16,08 (AP) , 04 (AP) 

MOVL 

4 (AP) ,R3 

ADDL 

#15, R3 

MOVB 

(R3) ,  R2 

BICL3 

#AXFFTTFFFO , R2 , R4 

CMPB 

#AX0F,R4 

BNEQ 

CNTNU 

BICL2 

#AX00000002,R2 

% 

BRB 

INVEND 

CNTNU : 

BICL2 

#AX0000000E,R4 

CMPB 

#1,  R4 

BEQL 

POS 

BICL2 

#AX0000000P,R2 

BISL2 

#AX0000000D,R2 

210 


CMU/SEI-89-TR-1 6 


BRB 

INVEND 

POS :  BICL2 

#AX0000000F,R2 

BISL2 

#AX0000000C,R2 

INVEND :  MOVB 

R 2,  (R3) 

RET 

/ 

/ 

;  PROCEDURE  ABSV 

;  procadura  absv  (Valua  :  in  out  Maz__D ac ima 1 ; 

Right  :  Ma_x_Daci_mal)  ; 

/ 

;  —  th_i»  procadura  return*  tba  absolute*  valua  of  Right  in  Valua 

/ 

.PSECT 

ABSV 

.ENTRY 

ABSV  AM<R2,  R3> 

M0VC3 

#16,  @8 (AP) , @4 (AP) 

MOVL 

4  (AP)  ,R3 

ADDL 

#15,  R3 

MOVB 

(R3) ,R2 

BICL2 

#AX0000000F,R2 

BISL2 

#AXOOOOOOOC, R2 

MOVB 

R2,  (R3) 

RET 

PROCEDURE  SHFT 

procadura  ah  ft:  (Raault  :  out  Max_Dacimal  ; 

Valua  :  MaxJDacimal; 

acala  :  intagar; 

arror  :  In  out  boolaan) ; 

—  this  procadura  ahif ta  tha  31  digits  of  Valua  by  "acala" 

—  digit a.  if  "acala"  ia  positiva,  tha  ahift  ia  laft. 

—  if  "acala"  ia  nagativa,  tha  ahift  ia  right.  If  ovarflow 

—  occur*  on  a  laft  ahift,  than  tha  arror  boolaan  ia  aat  to 

—  trua.  Tha  right  ahift  rounds  tha  raoaining  digits. 


■PSECT  SHFTDATA 
SDATA:  . BLKB  16 

.PSECT  SHFT 

.ENTRY  SHFT  AM<R2,  R3,  R4,  R5> 
MOVL  @12(AP),R4 

AS  HP  R4,  #31,  @8  (AP)  ,  #5,  #31,  04  (AP) 

BVS  OVFLW 

RET 

OVFLW:  MOVL  #1,@16(AP) 

RET 


PROCEDURE  EQ 

procadura  agual  (Laft,  Right  :  Max_Dacimal ; 

raault  :  in  out  boolaan) ; 

—  this  procadura  cospara*  Laft  and  Right,  and  ratums  a  raault 

—  of  trua  if  thay  ara  agual,  or  falaa  if  thay  ara  not  agual 


.PSECT  EQ 


I 

I 
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procedure  gr*ater_th*n_equal  (Left,  Right  :  Max_Decimal ; 

result  in  out  boolean) ; 

—  this  procedure  compare*  Left  and  Right .  if  Left  >=  Right 

—  then  result  is  set  to  true. 


.PSECT  GEQ 

•  ENTRY  GEQ  ■'M<R2,  R3> 
CMPP3  #31, 84 (AP) , 88 (AP) 
BGEQ  GEQTRU 
RET 

GEQTRO:  MOVL  #1, @12 (AP) 

RET 


PROCEDURE  ADD 

procedure  add  (Result  :  in  out  Max  Decimal; 

Left,  Right  :  Max  Pec ima  1 ; 
error  :  in  out  boolean) ; 

—  this  procedure  adds  Left  and  Right,  and  stores  the  result 

—  in  Result.  if  an  overflow  occurs  during  the  operation,  then 

—  "error"  is  set  to  true. 


.PSECT  ADD 

.ENTRY  ADD  ~M<R2,  R3,  R4,  R5> 

AD  DP  6  #31, 812  (AP)  ,  #31,  88  (AP) ,  #31,  84  (AP) 

BVS  ADDERR 

RET 

ADDERR:  MOVL  #1,816(AP) 

RET 


PROCEDURE  SUB 

procedure  subtract  (Result  :  in  out  Max_Decimal; 

Left,  Right  :  Msx_Decimal; 
error  :  in  out  boolean) ; 

—  this  procedure  subtracts  Right  from  Left,  and  stores  the  result 

—  in  Result.  if  an  overflow  occurs  during  the  operation,  the 

—  "error"  boolean  is  set  to  true. 


.PSECT  SUB 

•ENTRY  SUB  ~M<R2,  R3,  R4 ,  R5> 

SUBP6  #31,812 (AP) , #31, 88 (AP) , #31, 84 (AP) 

BVS  SUBERR 

RET 

SUBERR:  MOVL  #1, 818 (AP) 

RET 


PROCEDURE  MUL 

procedure  multiply  (Result  :  in  out  Max_Decimal; 

Left,  Right  :  Max_Decimal; 
error  :  in  out  boolean) ; 
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;  —  thia  procadu;*  raultipliae  Laft  by  Right,  and  atoraa  tha  raault 
;  —  in  Raault .  if  an  overflow  occur*  during  tha  oparation,  tha 
;  —  "arror"  boolaan  ia  aat  to  trua . 


.PSECT  MOL 

•  ENTRY  MOL  AM<R2,  R3 ,  R4 ,  R5> 

MOLP  #31,  @12  (AP)  ,  #31,  @8  (AP)  ,  #31,  @4  (AP) 

BVS  MOLERR 

RET 

MOLERR:  MOVL  #1,@16(AP) 

RET 


;  PROCEDORE  DIV 

;  procadura  divida  (Raault  :  in  out  Max_Dacimal  ; 

;  Laft,  Right  :  Max_D«ciml; 

;  Shift  :  in  out  intagar; 

;  arror  :  in  out  boolaan) ; 

/ 

;  —  thia  procadura  dividaa  Laft  by  Right,  and  atoraa  tha  raault 
;  —  in  Raault .  no  ovarf low  can  occur  uaing  thia  inatruction . 

;  —  thia  procadura  doaa  not  protact  tha  application  from  tha 
;  —  divida -by- zaro  run-tima  axcaption . 

/ 

•PSECT  DIV 
SHFTMP:  . BLKB  16 

•ENTRY  DIV  AM<R2,  R3,  R4,  RS,  R6,  R7,  R8> 

MOVL  #31, R4 
MOVL  8(AP),R5 
CLRL  R8 
LOOP  A:  IN CL  R8 

MOVB  (R5),R6 

BICL3  #-xFFFFFFOF, R6,  R7 

CMPB  #AX00,R7 

BNEQ  DONEA 

DECL  R4 

CMPB  #AX00 , R4 

BEQL  DONEA 

IN  CL  R8 

BICL3  #AXFFFFFFFO , R6 ,  R7 
CMPB  #AX00,R7 
BNEQ  DONEA 
DECL  R4 
CMPB  #AX00,R4 
BEQL  DONEA 
IN CL  R5 

BRB  LOOPA 
DONEA:  DECL  R8 

AS  HP  R8,  #31,  @8  (AP)  ,  #5,  #31,  SHFTMP 

DIVP  #31, @12 (AP), #31, SHFTMP, #31, @4 (AP) 

MOVL  R8, @16 (AP) 

RET 
•  END 
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C.21  SQL_Decimal  Assembler  Support  (IBM) 

Note:  At  the  time  this  document  was  published,  this  code  had  not  yet  been  fully  tested. 
Electronically  distributed  versions  of  this  code  will  be  updated  to  reflect  any  changes  made 
during  testing. 


AD AS UP  CSECT 

* - - 

* 

"  *KoC2DUK£  Ml 


*  procedure  mask  interrupts ; 


*  —  this  procedure  turns  off  bit  37  in  tbs  PSW,  to  prevent 

*  —  the  decimal  overflow  exception  from  causing  an  interrupt 

* 

* _ 


ENTRY 

MI 

SAVE 

(2/3) 

BALR 

3,0 

USING 

*  ;  3 

SR 

2,2 

CLEAR  R2 

O 

2,=X' OBOOOOOO ' 

OR  IN  THE  PROGRAM  MASK 

SPN 

2 

TURN  OFF  BIT  37  OF  THE  PSW 

RETURN 

(2,3) 

*  PROCEDURE  I2D 

* 

*  procedure  integer_to_decimal  (Value  :  in  out  Max_Decimal; 

*  Right  :  integer) ; 

* 


*  —  this  procedure  converts  an  integer  into  a  packed  decimal 

*  —  number  31  digits  long 


ENTRY 

I2D 

SAVE 

(2,5) 

BALR 

5,0 

USING 

*,  5 

LM 

2, 3, 0(1) 

ADDRESS 

OF  VALUE 

IN 

R2; 

RIGHT  IN  R3 

XC 

0(8, 2), 0(2) 

CLEAR  UPPER  2  WORDS 

OF 

DEC  RESULT 

CVD 

3,8(2) 

CONVERT 

INTEGER, 

STORE 

IN  WRDS  364 

RETURN 

(2,5) 

*  PROCEDURE  D2I 

* 


*  procedure  decimal_to_integer  (Value  :  in  out  integer; 

*  Right  :  Max_Decimal; 

*  error  :  in  out  boolean) ; 

* 

*  —  this  procedure  converts  a  packed  decimal  number  of  31 

*  —  digits  into  an  integer 

* 


*  This  procedure  will  cause  a  numeric  arror  to  occur  in  the 

*  application  if  the  number  to  be  converted  falls  outside  the 

*  range  -2147483648. .2147483647 

* 

• _ — _ _ _ _ _ _ _ _ _ _ _ _ 


ENTRY  D2Z 


CMU/SEI-69-TR-1 6 


215 


D2Z 

SAVE 

(2,  5) 

BALR 

5, 0 

OSINS 

* ,  5 

L 

3,4(1) 

ADDRESS  OF  RIGHT  IN  R3 

CP 

0(16,3) , LOWER (16) 

COMPARE  INPUT  TO  MAX  NEG  INTEGER 

BL 

D2IEPR 

IF  LESS  THAN,  OVERFLOW  WILL  OCCUR 

CP 

0(16,3) , UPPER (16) 

COMPARE  INPUT  TO  MAX  POS  INTEGER 

BH 

D2IERR 

IF  GREATER  THAN,  OVERFLOW  WILL  OCCUR 

CVB 

4,8(3) 

CNVT  LOWER  8  BYTES  OF  DECIMAL  NUM 

ST 

4,0(1) 

STORE  RESULT 

B 

D2IRET 

GO  TO  D2IRET 

D2IERR 

L 

2,«F' 1' 

SET  VALUE  OF  ERROR  BOOLEAN 

STC 

2,8(1) 

TO  'TRUE' 

D2IRET 

RETURN 

(2,5) 

* 


*  PROCEDURE  NS2D 

*  procedure  nuroeric_atring_to_dec i ma 1  (Value  in  out  Max_Decimal; 

«  Right  :  etring) ; 

* 

*  —  this  procedure  converts  e  numeric  string  of  31  digits  and  a 

*  —  sign  from  leading  separate  numeric  format  into  a  packed 

*  —  decimal  number  of  31  digits 

* 


* _ 

ENTRY 

NS2D 

NS2D 

SAVE 

(2,5) 

BALR 

5,0 

USING 

*,s 

Ui 

2, 3, 0(1) 

GET  ADDRESSES  OF  PARMS 

PACK 

0(9, 2), 1(16, 3) 

CK  FRST  16  DIGS  INTO  FRST  9  BYTES 

SRP 

0(9, 2), 1,5 

SHFT  LFT,  SO  16  VALID  DIGS  IN  8  BYTS 

PACK 

8(8,2) ,17(15,3) 

PACK  LAST  15  DIGS  INTO  LAST  8  BYTES 

CLC 

0(1,3),«X'4E' 

CHECK  SIGN 

BE 

NS2DPOS 

BRANCH  TO  MAKE  RESULT  POSITIVE 

Ml 

15(2) ,X'F0' 

CLEAR  SIGN  DIGIT 

OI 

15(2) ,X'0D' 

MAKE  RESULT  NEGATIVE 

B 

NS2DRET 

RETURN  AFTER  MAKING  RESULT  NEGATIVE 

NS2DPOS 

NI 

15(2) .X'FO' 

CLEAR  SIGN  DIGIT 

OI 

15(2) ,X'0C' 

MAKE  RESULT  POSITIVE 

NS2DRET 

RETURN 

(2,5) 

* 

« 


*  PROCEDURE  D2NS 

* 

*  procedure  decimal  to_numeric_string  (Value  :  in  out  string; 

*  Right  :  Max_Decimal) ; 

* 

*  —  this  procedure  converts  a  packed  decimal  number  of  31  digits 

*  —  into  a  numeric  string  in  leading  separate  numeric  format 

* 


* - 

ENTRY 

D2NS 

D2NS 

SAVE 

(2,5) 

BALR 

5,0 

USING 

* ,  5 

LM 

2, 3, 0(1) 

GET  ADDRESSES  OF  PARMS 

UNPK 

1(15,2) ,0(8,3) 

UNPACK  FIRST  14  DIGITS 

UNPK 

15(15,2) ,7(8,3) 

UNPACK  NEXT  14  DIGITS 

UNPK 

29(3,2) ,14(2,3) 

UNPACK  LAST  3  DIGITS 

SR 

4,4 

CLEAR  R4 

IC 

4,15(3) 

GET  SIGN  OF  INPUT 
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N 

4 , =X' OOOOOOOF 

CL 

4 , =X' OOOOOOOD 

BE 

D2NSNEG 

MVI 

0(2)  ,X'4E' 

B 

D2NSTR 

D2NSNEG 

MVI 

0 (2) ,X' 60' 

D2NSTR 

01 

31(2) , X' FO' 

RETURN 

(2,5) 

AND  OUT  NUMERIC  PORTION  OF  BYTE 

CHECK  THE  SIGN 

IF  NEGATIVE,  GO  TO  D2NSNEG 

MAKE  POSITIVE 

GO  TO  D2NSTR 

MAKE  NEGATIVE 

MAKE  LAST  BYTE  EBCDIC 


* 

*  PROCEDURE  LZ 

• 

*  procedure  leading_zaroea  (Value  :  Max  Decimal; 

*  intag  :  integer; 

*  digs  :  in  out  integer) ; 

* 


*  —  this  procedure  return!  the  number  of  leading  zeroea  in  the 

*  —  first  ''intag''  digita  of  the  packed  decimal  number 

* 


ENTRY 

LZ 

LZ 

SAVE 

BALR 

USING 

(2,8) 

8,0 

*,e 

LM 

2, 3, 0(1) 

GET  PARMS  IN  R2  AND  R3 

BCTR 

2,0 

OFFSET  ADDRESS  BY  ONE  FOR  LOOP 

SR 

5,5 

CLEAR  R5 

SR 

6,6 

CLEAR  R6 

LOOP 

LA 

2,1(2) 

get  NEXT  BYTE  TO  LOOK  AT 

LA 

5,1(5) 

ADD  1  TO  R5  (COUNT  OF  ZERO  DIGITS+1) 

IC 

6,0(2) 

GET  ANOTHER  BYTE  OF  PARM1 

SR 

7,7 

CLEAR  R7 

SRDL 

6,  4 

UPPER  NIBBLE  OF  BYT  IN  R6,  LWR  IN  R7 

C 

6, ZERO 

IF  R6  IS  ZERO,  CONTINUE 

BNE 

DONE 

IF  NOT,  DONE 

BCT 

3 , CONT 

GET  NEXT  NIBBLE  IF  MORE  TO  SCAN 

B 

DONE2 

NO  MORE  TO  SCAN 

CONT 

LA 

5,1(5) 

ADD  1  TO  R5  (COUNT  OF  ZERO  DIGITS+1) 

C 

7, ZERO 

IF  R7  IS  ZERO,  CONTINUE 

BNE 

DONE 

IF  NOT,  DONE 

BCT 

3, LOOP 

GOTO  LOOP  IF  NOT  FINISHED 

B 

D0NE2 

NO  NEED  TO  SUBT  1,  ALL  ZEROES 

DONE 

BCTR 

5,0 

R5  NOW  CONTAINS  COUNT  OF  ZERO  DIGITS 

DONE2 

ST 

5,8(1) 

STORE  RESULT 

* - . 

RETURN 

(2,8) 

*  PROCEDURE  TZ 

* 


*  procedure  trailing  zeroea 

:  \ 


* 


(Value  :  Max_Decimal; 

a cal  :  decimal _ digita ; 

diga  :  in  out  integer) ; 


*  —  thia  procedure  returne  the  number  of  trailing  zeroea  in 

*  —  the  laat  "acal"  digita  of  the  packed  decimal  number 


ENTRY  TZ 

TZ  SAVE  (2,8) 

BALK  8,0 
USING  * , 8 
LM  2, 3, 0(1) 

LA  2,15(2) 


PARMS  IN  R2  AND  R3 

GET  ADDRESS  OF  LAST  BYTE  OF  DEC  NUMB 
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IC 

6,0(2) 

GET  LAST  BYTE  OF  DEC  NUMBER 

SRI 

6,  4 

GET  LAST  DIGIT  OF  DEC  NUMBER 

SR 

5,  5 

CLEAR  R5 

LOOP  1 

LA 

5,1(5) 

ADD  1  TO  R5  (COUNT  OF  ZERO  DIGITS+1) 

C 

6, ZERO 

IF  R6  IS  ZERO,  CONTINUE 

BNE 

DONE1 

IF  NOT,  DONE 

BCT 

3 , CONTI 

GET  NEXT  BYTE  IF  MORE  TO  SCAN 

B 

DONE3 

NO  MORE  TO  SCAN 

CONTI 

BCTR 

2,0 

GET  ADDRESS  OF  NEXT  BYTE  OF  DEC  NUMB 

IC 

6,0(2) 

GET  PREV  BYTE  OF  DEC  DIGIT 

SR 

7,7 

CLEAR  R7  FOR  SHIFT 

SRDL 

6,4 

UPPER  NIBBLE  «>  R6,  LOWER  =>  R7 

LA 

5,1(5) 

ADD  1  TO  R5  (COUNT  OF  ZERO  DIGITS+1) 

C 

7,  ZERO 

IF  R7  IS  ZERO,  CONTINUE 

BNE 

DONE1 

IF  NOT,  DONE 

BCT 

3 , LOOP1 

GO  TO  LOO  PI  IF  MORE  TO  SCAN 

B 

DONE3 

NO  NEED  TO  SUBT  1,  ALL  ZEROES 

DONE1 

BCTR 

5,0 

R5  NOW  CONTAINS  COUNT  OF  ZERO  DICITS 

DONE  3 

ST 

5,8(1) 

STORE  RESULT 

RETURN 

(2,8) 

* 

*  PROCEDURE  INV 
« 

*  proctdur*  invar**  (Valua  :  in  out  Max_Dacimal; 

*  Right  :  Max_D ac  im*l )  ; 

* 

*  —  thin  procadur*  ratumi  tha  invar**  of  Right  in  Valua 
« 


ENTRY 

INV 

INV 

SAVE 

(2,6) 

BALR 

6,0 

USING 

* ,  6 

LM 

2, 3, 0(1) 

GET  ADDRESSES  OF  PARAMS 

MVC 

0(16,2)  ,0(3) 

MOVE  INPUT  TO  OUTPUT 

IC 

4,15(2) 

LOAD  LAST  BYTE  OF  DEC  NUMBER 

SR 

5,5 

CLEAR  R5  FOR  SHIFT 

SRDL 

4,4 

SHIFT  RIGHT  SO  ONLY  SIGN  IN  R5 

C 

5 , POSZCON 

IS  SIGN  AN  'F' 

BNE 

CNTNU 

CO  TO  CNTNU  IF  NOT 

L 

5 , NEGCON 

ELSE  MAKE  THE  SIGN  NEGATIVE 

B 

INVEND 

GO  TO  END 

CNTNU 

SLL 

5,3 

SHIFT  TO  SEE  LOW  ORDER  BIT  OF 

SIGN 

C 

5, ZERO 

IF  LOW  ORDER  BIT  IS  ZERO,  NUM 

IS  POS 

BNE 

POS 

IF  LOW  ORDER  BIT  IS  ONE,  NUM 

IS  NEC 

L 

5 , NEGCON 

DEC  NUM  IS  POS  =>  MAKE  NEC 

B 

INVEND 

GO  TO  END 

POS 

L 

5 , POSCON 

DEC  NUM  IS  NEC  =>  MAKE  POS 

INVEND 

SLDL 

4,4 

SHIFT  LEFT  SO  LOW  ORDER  BYTE 

IN  R4 

STC 

4,15(2) 

STORE  LOW  ORDER  BYTE  INTO  DEC 

NUM 

INVRET 

RETURN 

(2,6) 

*  PROCEDURE  ABSV 

• 

*  procadur*  *db«v  (Valua  :  in  out  Max_Dacimal ; 

*  Right  :  Max  Dacimal) ; 

* 

*  —  this  procadur*  raturn*  tha  abaoluta  valua  of  Right  in  Valua 

*  _ _ _ _ _ _ _ _ _ _ _ 

ENTRY  ABSV 
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ABSV 


SAVE  (2,4) 

BALK  4,0 
USING  * ,  4 
1M  2, 3, 0(1) 

MVC  0(16,  2),  0(3) 
NI  15(2), X'FO' 

01  15(2), X'OC' 

RETURN  (2,4) 


GET  ADDRESSES  OF  PARAMS 
MOVE  INPUT  TO  OUTPUT 
CLEAR  SIGN 
MAKE  SIGN  POS 


* 

*  PROCEDURE  SHFT 

* 

*  prooadur*  ahf  t  (Reault  :  out  Max_Decimal; 

*  Value  :  Max  Dteinal; 

*  aoala  :  integer; 

*  error  :  in  out  boolean) ; 

* 


*  —  this  procedure  ehifte  the  31  digita  of  Value  by  "acale” 

*  —  digita.  if  "acale"  ia  poaitive,  the  ahift  ia  left. 

*  —  if  "acale"  ia  negative,  the  ahift  ia  right.  If  overflow 

*  —  occura  on  a  left  ahift,  then  the  error  boolean  ia  aet  to 

*  —  true.  The  right  ahift  rounda  the  remaining  digita. 

* 

*  Thia  aubroutine  expect  a  that  the  Decimal  Overflow  maak  in  the  PSW 

*  haa  been  cleared  to  prevent  the  interrupt  (bit  poa  37) . 

* 

* _ 

ENTRY  SHFT 


SHFT 

SAVE 

(2,6) 

BALR 

6,  0 

USING 

*,  6 

LM 

2, 4,0(1) 

GET  PARMS  IN  R2  THROUGH  R4 

MVC 

0(16, 2), 0(3) 

MOVE  THE  INPUT  TO  THE  OUTPUT 

L 

3,«X' 0F5' 

LOAD  LENGTH 1  AND  LENCTH2  FOR  EX  INST 

C 

4,-F' 64' 

IF  SHIFT  COUNT  >  64 

BH 

SHFTERR 

THEN  COUNT  OUTSIDE  SHIFT  RANGE 

C 

4,-F' -64' 

IF  SHIFT  COUNT  <  -64 

BL 

SHFTERR 

THEN  COUNT  OUTSIDE  SHIFT  RANGE 

C 

4,-F' 0' 

IF  SHIFT  COUNT  >-  0 

BNL 

SHFTCNT 

THEN  CONTINUE,  ELSE 

L 

5,-F' 64' 

SHIFT  IS  TO  RIGHT,  2ND  OPND  IS 

SR 

5,4 

64  -  COUNT 

LR 

4,5 

CET  COUNT  IN  R4 

SHFTCNT 

N 

4 , — X' 00000FFF ' 

ONLY  LONER  12  BITS  CONTAINS  COUNT 

STB 

4 , INST+4 

STORE  COUNT  INTO  SHIFT  INSTRUCTION 

EX 

3, INST 

EXECUTE  INSTRUCTION 

BO 

SHFTERR 

IF  OVERFLOW,  GO  TO  SHFTERR 

B 

SHFTRET 

GO  TO  SHFTRET 

SHFTERR 

LA 

4, 1 

LOAD  ’TRUE'  IN  R4 

STC 

4,12(1) 

STORE  'TRUE'  INTO  ERROR  BOOLEAN 

SHFTRET 

• _ _ 

RETURN 

(2,6) 

PROCEDURE  EQ 

procedure  equal  (Left,  Right  :  Max^Decimal ; 

result  :  in  out  boolean) ; 

—  thi -  procedure  cotparea  Left  and  Right,  and  returns  a  result 

—  of  true  if  they  are  equal,  or  false  if  they  are  not  equal 


ENTRY  EQ 
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LEQ 


SAVE  (2,5) 

BALE  5,0 
USING  * , 5 

LM  2, 3, 0(1)  SET  ADDRESSES  OF  PARMS 

CP  0  (16, 2) , 0 (16, 3)  COMPARE  TWO  PACKED  HUMS 

EH  LEQRET  RETURN  'FALSE'  IF  NOT  LEQ 

LA  2,1  LOAD  'TRUE'  INTO  R2 

STC  2,8(1)  STORE  'TRUE'  INTO  RESULT  BOOLEAN 

LEQRET  RETURN  (2,5) 


•  PROCEDURE  GEQ 

• 

*  procedure  great*r_than_equal  (Left,  Right  :  Max_D*cimal ; 

*  result  :  in  out  bool* so) ; 

* 

*  —  this  procedure  comperes  L*ft  end  Right.  if  L*ft  >■=  Right 

*  —  then  result  is  set  to  true . 

* 


GEQ 


ENTRY 

GEQ 

SAVE 

(2,5) 

BALR 

5,0 

USING 

*,5 

LM 

2, 3, 0(1) 

GET  ADDRESSES  OF  PARMS 

CP 

0(16,2)  ,0(16,3) 

COMPARE  TWO  PACKED  HUMS 

BL 

GEQRET 

RETURN  'FALSE'  IF  NOT  CE( 

LA 

2,1 

LOAD  'TRUE'  INTO  R2 

STC 

2,8(1) 

STORE  'TRUE'  INTO  RESULT 

RETURN 

(2,5) 

I 

I 


GEQRET 

*  - 

* 

*  PROCEDURE  ADD 

*  procedure  add  (Result  :  in  out  Max_Decimal; 

*  Left,  Right  :  Max_Decimal ; 

*  error  :  in  out  boolean) ; 

* 


*  —  this  procedure  adds  Left  and  Right,  and  stores  the  result 

*  —  in  Result .  if  an  overflow  occurs  during  the  operation,  then 

*  —  "error"  is  set  to  true. 

* 

*  This  subroutine  expects  that  the  Decimal  Overflow  mask  in  the  PSW 

*  has  been  cleared  to  prevent  the  interrupt  (bit  pos  37) . 

* 


ENTRY 

ADD 

ADD 

SAVE 

(2,5) 

BALR 

5,0 

USING 

* ,  5 

LM 

2, 4, 0(1) 

GET  ADDRESSES  OF  PARMS 

MVC 

0(16,2)  ,0(3) 

MOVE  'LEFT'  TO  'RESULT' 

AP 

0(16,2) ,0(16,4) 

ADD  'LEFT'  AND  'RIGHT'  IN  PLACE 

BO 

ADDERR 

GO  TO  ADDERR  ON  OVERFLOW 

B 

ADDRET 

GO  TO  ADDRET 

ADDERR 

LA 

3,1 

LOAD  'TRUE'  INTO  R3 

STC 

3,12(1) 

STORE  'TRUE'  INTO  ERROR  BOOLEAN 

ADDRET 

RETURN 

(2,5) 

*  PROCEDURE  sub 

* 

•  procedure  subtract  (Result  :  in  out  Max  Decimal; 
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*  La ft,  Right  :  Max_Decimal; 

*  tzror  :  in  out  boolean) ; 

* 

*  —  this  procedure  subtracts  Right  from  Laft,  and  storas  tha  result 

*  —  in  Rasult .  if  an  overflow  occurs  during  tha  oparation,  tha 

*  —  "azror"  boolean  is  sat  to  trua . 

* 

*  This  subroutina  expects  that  tha  Decimal  Ovarf low  mask  in  tha  PSW 

*  has  baan  claarad  to  prevent  tha  intarrupt  (bit  pos  37) . 

* 


* - - 

ENTRY 

SUB 

SUB 

SAVE 

(2,5) 

BALR 

5,0 

USING 

*,5 

LM 

2, 4, 0(1) 

MVC 

0(16,2)  ,0(3) 

SP 

0(16,2) ,0(16,4) 

BO 

SUBERR 

B 

SUBRET 

SUBERR 

LA 

3,1 

STC 

3,12(1) 

SUBRET 
* - 

RETURN 

(2,5) 

SET  ADDRESSES  OF  PARMS 
MOVE  'LEFT'  TO  'RESULT' 

SUBTRACT  'RIGHT'  FROM  'LEFT' 

SO  TO  SUBERR  ON  OVERFLOW 
SO  TO  SUB RET 

LOAD  'TRUE'  VALUE  INTO  R3 
STORE  'TRUE'  INTO  ERROR  BOOLEAN 


*  PROCEDURE  MUL 

* 

*  procedure  multiply  (Rasult  :  in  out  Max_Dacimal; 

*  Laft,  Right  :  Max_Decimal; 

*  error  :  in  out  boolean) ; 


*  —  this  procedure  multiplies  Laft  by  Right,  and  storas  tha  rasult 

*  —  in  Rasult .  if  an  overflow  occurs  during  tha  oparation,  tha 

*  —  "error"  boolean  is  sat  to  trua. 

* 

*  This  procedure  will  causa  a  numeric  error  to  occur  in  tha  application 

*  if  there  are  not  enough  leading  zeros  in  the  multiplicand  to 

*  accomodate  tha  MP  instruction. 

* 


* 


MUL 


LOOPA 


CONTA 


ENTRY 

MUL 

SAVE 

(2,10) 

BALR 

10,0 

USING 

*,10 

LM 

2, 4, 0(1) 

SET  ADDRESSES  OF  PARMS 

BCTR 

3,0 

OFFSET  'LEFT'  TO  PREPARE  FOR  LOOPA 

LA 

5,31 

GET  NUMBER  OF  DIGITS  TO  SCAN 

SR 

6,6 

CLEAR  R6 

SR 

8,8 

CLEAR  R8 

LA 

3,1(3) 

GET  ADDRESS  OF  NEXT  BYTE  TO  SCAN 

LA 

6,1(6) 

ADD  1  TO  R6  (COUNT  OF  ZERO  DIGITS+1) 

IC 

8,0(3) 

GET  ANOTHER  BYTE  OF  LEFT 

SR 

9,9 

CLEAR  R9 

SRDL 

8,4 

UPPER  NIBBLE  OF  BYT  IN  R8,  LWR  IN  R9 

C 

8, ZERO 

IF  R8  IS  ZERO,  CONTINUE 

BNE 

DONEA 

IF  NOT,  DONE 

BCT 

5, CONTA 

CONTINUE  IF  MORE  TO  SCAN 

B 

DONEA1 

NO  MORE  TO  SCAN 

LA 

6,1(6) 

ADD  1  TO  R6  (COUNT  OF  ZERO  DIGITS+1) 

C 

9, ZERO 

IF  R9  IS  ZERO,  CONTINUE 

BNE 

DONEA 

IF  NOT,  DONE 

BCT 

5, LOOPA 

GET  NEXT  BYTE  IF  MORE  TO  SCAN 

B 

DONEA 1 

NO  NEED  TO  SUBT  1,  ALL  ZEROES 
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DONEA 

DONEA1 


LOOPB 


CONTB 


DO  NEB 
DONEB1 


MULV1 


MULV2 


MULE RE 
MULRET 


BCTR 

6,0 

R6  NOW  CONTAINS  COUNT  OF  ZERO  DIGITS 

LA 

5,31 

GET  NUMBER  OF  DIGITS  TO  SCAN 

SR 

7,7 

CLEAR  R7 

BCTR 

4,0 

OFFSET  'RICHT'  TO  PREPARE  FOR  LOOPB 

SR 

8, 8 

CLEAR  R8 

LA 

4,1(4) 

GST  ADDRESS  OF  NEXT  BYTE  TO  SCAN 

LA 

7,1(7) 

ADD  1  TO  R7  (COUNT  OF  ZERO  DIGITS+1) 

IC 

8,0(4) 

GET  ANOTHER  BYTE  OF  RIGHT 

SR 

9,9 

CLEAR  R9 

SRDL 

8,4 

UPPER  NIBBLE  OF  BYT  IN  R8,  LWR  IN  R9 

C 

8, ZERO 

IF  R8  IS  ZERO,  CONTINUE 

BNE 

DONEB 

IF  NOT,  DONE 

BCT 

5, CONTB 

SCAN  NEXT  NIBBLE  IF  MORE  TO  SCAN 

B 

DONEB 1 

NO  MURE  TO  SCAN 

LA 

7,1(7) 

ADD  1  TO  R7  (COUNT  OF  ZERO  DIGITS+1) 

C 

9, ZERO 

IF  R9  IS  ZERO,  CONTINUE 

BNE 

DONEB 

IF  NOT,  DONE 

BCT 

5, LOOPB 

GET  NEXT  BYTE  TO  SCAN  IF  MORE 

B 

DONEB 1 

NO  NEED  TO  SUBT  1,  ALL  ZEROES 

BCTR 

7,0 

R7  NOW  CONTAINS  COUNT  OF  ZERO  DIGITS 

LM 

3, 4, 4(1) 

GET  ADDRESSES  OF  LEFT  AND  RICHT 

CR 

6,7 

WHICH  OPERAND  HAS  MORE  ZEROES? 

BH 

MULV2 

GO  TO  MULV2  IF  RIGHT  HAS  MORE  ZEROES 

SRL 

6,1 

CLEAR  LOW  ORDER  BIT 

SLL 

6,1 

MAXE  ODD  #  OF  LEADING  0'S  EVEN 

LR 

8,6 

LOAD  R8  WITH  f  LEADING  O' S  OF  LEFT 

AR 

8,7 

ADD  IN  «  LEADING  0'S  OF  RIGHT 

C 

8 ,  THTYTWO 

IF  NOT  GREATER  THAN  31,  THEN 

BL 

MOLERR 

MULTIPLY  WILL  RAISE  AN  EXCEPTION 

MVC 

0(16, 2), 0(4) 

LEFT  HAS  MORE  ZEROES:  MOVE  RIGHT 

LA 

8,32 

TO  RESULT 

SR 

8,6 

R8  CONTAINS  NUM  DIGITS  IN  LEFT 

SRL 

8,1 

DIVIDE  NUM  DIGS  BY  2  TO  GET  NUM  BYTS 

LA 

8,1(8) 

ADD  IN  REM  TO  GET  NUM  BYTES  IN  LEFT 

LA 

3,16(3) 

ADD  16  TO  LEFT 

SR 

3,8 

SUB  NUM  BYTES  TO  GET  CORRECT  OFFSET 

BCTR 

8,0 

OFFSET  LENGTH  OF  LEFT  BY  1 

O 

8,»X'  000000F0' 

OR  IN  LENGTH  OF  RESULT 

EX 

8 , MULV1A 

EXECUTE  MP  INSTR  USING  LENGTHS  IN  R9 

B 

MULRET 

CO  TO  MULRET 

SRL 

7,1 

CLR  LOW  ORDER  BIT,  ODD  #  OF  LDNC  0'S 

SLL 

7,1 

MAKE  ODD  f  OF  LEAD INC  0'S  EVEN 

LR 

8,7 

LOAD  R8  WITH  #  LEADING  O' S  OF  RIGHT 

AR 

8,6 

ADD  IN  #  LEADING  0' S  OF  LEFT 

C 

8, THTYTWO 

IF  NOT  GREATER  THAN  31,  THEN 

BL 

MULERR 

MULTIPLY  WILL  RAISE  AN  EXCEPTION 

MVC 

0(16, 2), 0(3) 

RIGHT  HAS  MORS  ZEROES:  MOVE  LEFT 

LA 

8,32 

TO  RESULT 

SR 

8,7 

R8  CONTAINS  NUM  DIGITS  IN  RIGHT 

SRL 

8,1 

DIVIDE  NUM  DIGS  BY  2  TO  GET  NUM  BYTS 

LA 

8,1(8) 

ADD  IN  REM  TO  GET  NUM  BYTES  IN  RIGHT 

LA 

4,16(4) 

ADD  16  TO  RICHT 

SR 

4,8 

SUB  NUM  BYTES  TO  GET  CORRECT  OFFSET 

BCTR 

8,0 

OFFSET  LENGTH  OF  RIGHT  BY  1 

O 

e,«x' oooooopo' 

OR  IN  LENGTH  OF  RESULT 

EX 

8 , MULV2A 

EXECUTE  MP  INSTR  USING  LENGTHS  IN  R9 

B 

MULRET 

GO  TO  MULRET 

LA 

3,1 

PUT  VALUE  'TRUE'  INTO  R3 

STC 

3,12(1) 

STORE  R3  INTO  ERROR 

RETURN 

(2,10) 

*  PROCEDURE  DIV 
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*  procadura  di.vi.da  (Raault  :  in  out  Max_Da c ima  1 ; 

*  La  ft ,  Right  :  Max_Dacimal; 

*  Shift  :  in  out  intagar ; 

*  arror  :  in  out  boolaan) ; 

* 

*  —  thia  prooadura  dividaa  La ft  by  Right,  and  atoras  tha  raault 

*  —  in  Raault.  no  ovarflow  can  occur  uaing  thia  inatruction. 

*  —  thia  procadura  doaa  not  protact  tha  application  from  tha 

*  —  divida-by-iaro  run-tima  axcaption. 

*  Thia  procadura  cauaaa  a  nunaric  arror  axcaption  to  occur  in 

*  tha  application  if  tha  raault  ia  too  larga  for  tha  apaca 

*  aat  aaida  for  tha  quotiant  by  tha  DP  (divida  packad)  inatruction, 


*  or 

* 

if  tha 

actual  numbar 

in  tha  diviaor  ia  largar  than  8  bytaa . 

ENTRY 

DIV 

DIV 

SAVE 

(2,11) 

BALR 

11,0 

OSINS 

*,11 

LM 

2, 4, 0(1) 

GET  ADDRESSES  OF  PARMS 

BCTR 

3,0 

OFFSET  R3  TO  PREPARE  FOR  LOOPC 

LA 

10,31 

GET  NUMBER  OF  DIGITS  TO  SCAN 

SR 

6,6 

CLEAR  R6 

SR 

8,8 

CLEAR  R8 

LOOPC 

LA 

3,1(3) 

GET  ADDRESS  OF  NEXT  BYTE  TO  SCAN 

LA 

6,1(6) 

ADD  1  TO  R6  (COUNT  OF  ZERO  DIGITS-t-1) 

IC 

8,0(3) 

GET  ANOTHER  BYTE  OF  LEFT 

SR 

9,9 

CLEAR  R9 

SRDL 

8,4 

UPPER  NIBBLE  OF  BYT  IN  R8,  LWR  IN  R9 

C 

8, ZERO 

IF  R8  IS  ZERO,  CONTINUE 

BNE 

DONEC 

IF  NOT,  DONE 

BCT 

10, CONTC 

SCAN  NEXT  NIBBLE  IF  MORE  LEFT 

B 

DONEC1 

NO  MORE  TO  SCAN 

CONTC 

LA 

«,1(6) 

ADD  1  TO  R6  (COUNT  OF  ZERO  DIGITS+1) 

C 

9, ZERO 

IF  R9  IS  ZERO,  CONTINUE 

BNE 

DONEC 

IF  NOT,  DONE 

BCT 

10, LOOPC 

GET  NEXT  BYTE  IF  MORE  TO  SCAN 

B 

DONEC1 

NO  NEED  TO  SUBT  1,  ALL  ZEROES 

DONEC 

BCTR 

6,0 

R6  NOW  CONTAINS  COUNT  OF  ZERO  DIGITS 

DONE Cl 

BCTR 

4,0 

OFFSET  R4  TO  PREPARE  FOR  LOOPD 

LA 

10,31 

GET  NUMBER  OF  DIGITS  TO  SCAN 

SR 

7,7 

CLEAR  R7 

SR 

8,8 

CLEAR  R8 

LOOPD 

LA 

4,1(4) 

GET  ADDRESS  OF  NEXT  BYTE  TO  SCAN 

LA 

7,1(7) 

ADD  1  TO  R7  (COUNT  OF  ZERO  DIGITS+1) 

IC 

8,0(4) 

GET  ANOTHER  BYTE  OF  RIGHT 

SR 

9,9 

CLEAR  R9 

SRDL 

8,4 

UPPER  NIBBLE  OF  BYT  IN  R8,  LWR  IN  R9 

C 

8,  ZERO 

IF  R8  IS  ZERO,  CONTINUE 

BNE 

DONED 

IF  NOT,  DONE 

BCT 

10, CONTD 

CHECK  NEXT  NIBBLE  IF  MORE  TO  SCAN 

B 

DONED 1 

NO  MORE  TO  SCAN 

CONTD 

LA 

7,1(7) 

ADD  1  TO  R7  (COUNT  OF  ZERO  DIGITS+1) 

C 

9,  ZERO 

IF  R9  IS  ZERO,  CONTINUE 

BNE 

DONED 

IF  NOT,  DONE 

BCT 

10, LOOPD 

GET  NEXT  BYTE  IF  MORE  TO  SCAN 

B 

DONED 1 

NO  NEED  TO  SUBTRACT  1,  ALL  ZEROES 

DOMED 

BCTR 

7,0 

R7  NOW  CONTAINS  COUNT  OF  ZERO  DIGITS 

DOMED 1 

LM 

3, 4, 4(1) 

RESTORE  ADDRESSES  OF  PARMS 

C 

7, SXTEEN 

IS  DIVISOR  BIGGER  THAN  8  BYTES 

BL 

DIVERR 

ERROR  IF  YES 
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LA 

8,31 

SR 

8,6 

LA 

9,31 

SR 

9,7 

SRL 

7,1 

LA 

6,16 

SR 

6,7 

MVC 

0(16,2)  ,0(3) 

SR 

10,  10 

SR 

9,8 

BZ 

DIVCONT 

BP 

SHFTOP 

LCR 

10,9 

SHFTOP 

SRP 

0(16,2) ,9,5 

DIVCONT 

NX 

15(2) ,X'F0' 

OI 

15(2) ,X'0C' 

IC 

8,15(4) 

LR 

9,8 

N 

8 , =X' FFFFFFFO ' 

0 

8,=X' 0000000C' 

STC 

8,15(4) 

CP 

0(16,2) ,0(16,4) 

B L 

DIVCNT1 

LA 

10,1(10) 

DIVCNT1 

STC 

9, 15(4) 

AR 

4,7 

LR 

8,7 

SLL 

7,1 

BCTR 

7,0 

SR 

7,10 

BM 

DIVERR 

MVC 

0(16,2) ,0(3) 

BZ 

DODIV 

SRP 

0(16, 2), 7, 5 

B 

DODIVA 

DODIV 

SR 

7,7 

DODIVA 

BCTR 

6,0 

O 

6,*=X'  000000F0 ' 

EX 

6, DXVISN 

LA 

9,16 

SR 

9,8 

LR 

3,2 

LA 

3,15(3) 

AR 

2,8 

BCTR 

2,0 

MOVLOOP 

MVC 

0(1, 3), 0(2) 

BCTR 

8,0 

BZ 

NXTLP 

BCTR 

2,0 

BCTR 

3,0 

B 

MOVLOOP 

NXTLP 

BCTR 

2,0 

M0VLP1 

MVI 

0 (2) ,X' 00' 

BCTR 

9,0 

BZ 

FINMOV 

BCTR 

2,0 

B 

MOVLP1 

FINMOV 

ST 

7,12(1) 

B 

DXVRET 

DIVERR 

LA 

3,1 

STC 

3,16(1) 

DXVRET 

RETURN 

(2, 11) 

LOWER 

DC 

PL16' -2147483648' 

SET  MAX  DIGITS 

GET  NUM  DIGS  IN  DIVIDEND 

GET  MAX  DIGITS 

GET  NOM  DIGS  IN  DIVISOR 

DIVIDE  BY  2  =>  #  BYTES  OF  QUOTIENT 

LOAD  R6  WITH  IS 

R6  CONTAINS  #  BYTES  IN  DIVISOR 
MOVE  DIVIDEND  TO  RESULT  FOR  TEMP  USE 
CLR  RIO  TO  HOLD  NUMB  DIGS  OF  RIGHT 
COMP  LENGTH (LEFT)  WITH  LENGTH (RIGHT) 
GOTO  DIVCONT  IF  EQUAL 
GOTO  SHFTOP  IF  LENGTH (L)  <  LENGTH (R) 
MV  #DXCS  SHFTD  RGHT  TO  #DIGS  IN  RES 
SHIFT  DIVIDEND  FOR  COMPARE  W/ DIVISOR 
CLEAR  SIGN  OF  LEFT 
MAKE  SIGN  OF  LEFT  POSITIVE 
GET  SIGN  OF  RIGHT 
SAVE  SIGN  FOR  LATER 
CLEAR  SIGN  OF  RIGHT 
MAKE  SIGN  OF  RIGHT  POSITIVE 
STORE  SIGN  IN  RIGHT 
COMPARE  RIGHT  AND  LEFT 
IF  LEFT  >  RIGHT,  THEN  RESULT  WILL 
CONTAIN  ONE  MORE  DIGIT 
REPLACE  ACTUAL  SIGN  INTO  RIGHT 
GET  OFFSET  INTO  DIVISOR  OF  ACTL  NUM 
SAVE  #BYTES  IN  QUOTIENT 
GET  NUM  OF  DIGITS  +  1  OF  QUOTIENT 
GET  NOM  OF  DIGITS  OF  QUOTIENT 
COMP  #DIGS  IN  QUOTNT  TO  #DICS  IN  RES 
OVERFLOW  =>  GO  TO  DIVERR 
RESTORE  LEFT  IN  RESULT 
IF  EQUAL,  THEN  PERFORM  DIVISION 
SHIFT  LEFT  TO  GET  MAX  PREC  OF  RESULT 
GO  TO  DODIVA 
NO  SHIFT  TOOK  PLACE 
OFFSET  #BYTES  IN  DIVISOR  BY  ONE 
ADD  LENGTH  OF  DIVIDEND 
PERFORM  DIVIDE  OPERATION 
MOVE  16  INTO  R9 
R9  HAS  fBYTES  OF  ZEROS 
GET  ADDRESS  OF  RESULT  INTO  R3 
GO  TO  LAST  BYTE 
GET  LAST  BYTE  OF  RESULT  +  1 
GET  LAST  BYTE  OF  RESULT 
MOVE  CHARACTER 

SUBTRACT  1  FROM  TOTAL  TO  MOVE 

FINISHED 

GET  NEXT  BYTE 

GET  NEXT  BYTE 

MOVE  NEXT  BYTE 

GET  NEXT  BYTE 

STORE  ZERO 

SUBTRACT  ONE  FROM  R9 

FINISH  IF  NO  MORE  TO  MOVE 

OTHERWISE,  DECREMENT  ADDRESS 

MOVE  ANOTHER  BYTE  Or  ZEROES 

STORE  AMOUNT  OF  SHIFT  INTO  PARAM 

GO  TO  DXVRET 

PUT  VALUE  'TRUE'  INTO  R3 

STORE  R3  INTO  ERROR 
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OFFER 

DC 

PL16' 2147483648 

POSCON 

DC 

X'COOOOOOO' 

NECCON 

DC 

X'DOOOOOOO' 

POSZCON 

DC 

X'FOOOOOOO' 

ZERO 

DC 

P'  0' 

ONE 

DC 

P'l' 

SXTEEN 

DC 

F'  16' 

THTYTMO 

DC 

F'  32' 

MOL  VIA 

MP 

0  (0, 2) ,  0  (0, 3) 

M0LV2A 

MP 

0(0, 2), 0(0,4) 

DIVISN 

DP 

0(0, 2), 0(0, 4) 

END 

ADASUP 

Jp 


C.22  SQL_Char_Pkg  Specification 

with  SQL_Sy*tsm;  use  SQL  System; 

with  SQL_Boolean_Pkg;  us«  SQL  Boolean  Pkg; 

with  SQL  Standard; 

package  SQL_Char_Pkg 

is 

subtype  SQL_Char_Length  is  natural 
range  1  . .  MAXCHRLEN; 
subtype  SQL_Onpadded_Length  is  natural 
range  0~. .  MAXCHRLEN ; 

type  SQL_Char_Not_Null  is  new  SQL_Standard.Char; 

type  SQL_Char (Length  :  SQL_Char_Length)  is  limited  private; 

function  Null_SQL_Char  return  SQL_Char ; 

—  pragma  INLINE  (Null_SQL_Char) ; 

—  the  next  three  functions  convert  between 

—  null-bearing  and  non  null -bearing -types 
—  Without_Null_Base  and  With_Null_Base  are 

—  inverses  (mod.  null  values) 

—  see  also  SQL_Char_Ops  generic  package  below 
function  With_Null_Base (Value  :  SQL_Char_Not_Null) 

return  SQL_Char; 

—  pragma  INLINE  (With_Null_Base) ; 

—  Without_Null_Base  and  Hithout_Null  Base_Unpadded  raise 
null_value_error  on  the  null  input 

function  Hithout_Null_Base  (Value  :  SQL_Char)  return  SQL_Char_Not_Null; 

—  pragma  INLINE  (Without_Null_Base) ; 

—  Without_Null_Dnpadded_Base  removes  trailing  blanks  from 

—  the  input 

function  Hithout_Null_Unpadded_Base (Value  ;  SQL_Char ) 
return  SQL_Char_Not_Null ; 

—  pragma  INLINE  (Without_Null_Unpadded_Base ) ; 

—  axiom:  unpadded_Length(x)  •= 

Without_Null_Dnpadded_Base (x) ' Length 

—  both  functions  raise  null_value_error  if  x  is  null 

—  the  next  six  functions  convert  between  Standard . String 

types  and  the  SQL_Char  and  SQL__Char_Not_Null  types 
function  To_String  (Value  :  S QL_Char;_N ot^_Nu  1 1 ) 
return  String; 
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function  To_String  (Value  :  SQL_Ch*x ) 
return  String; 

function  To_Unpadded_String  (Value  :  SQL  Char_Not  Null) 
ratum  String; 

function  To_Unpadded_String  (Valua  :  SQL_Char) 
ratum  String; 

—  pragma  INLINE  (To_Onpaddad  String) ; 

—  this  INLINE  works  for  BOTE  functions ! I 
function  To_SQL_Char_Not_Null  (Valua  :  String) 

ratum  SQL_Char_Not_Null ; 
function  To_SQL_Char  (Valua  :  String) 
ratum  SQL_Char; 

—  pragma  INLINE  ( To_SQL_Char ) ; 

function  Unpadded_Length  (Valua  :  SQL_Char) 
ratum  S QL_U np adda d_La ngth ; 

—  pragma  INLINE  (Dnpaddad_Langth) ; 

procadura  Aaaign ( 

Laft  :  out  SQL_Char; 

Right  :  SQL_Char 

); 

—  pragma  INLINE  (Aaaign) ; 

—  Subatring  (x,  k,  m)  ratuma  tha  eubatring  of  x  starting 

—  at  position  k  (ralativa  to  1)  with  langth  m . 

—  ratuma  null  valua  if  x  is  null 

—  raiaaa  conatraint_arror  if  Start  <  1  or  Langth  <  1  or 

—  Start  +  Langth  -  1  >  z. Langth 
function  Substring  (Valua  :  SQL_Char; 

Start,  Langth  :  SQL_Char_Langth) 
ratum  SQL_Char; 

—  pragma  INLINE  (Subatring) ; 

—  "4"  ratuma  null  if  aithar  paraoatar  is  null; 

otharwisa  parforma  concatanation  in  tha  usual  way, 
prasarving  all  blanks. 

—  may  raiaa  conatraint_arror  implicitly  if  rasult  is 

too  larga  (i . a . ,  graatar  than  SQL_Char_Length' Last 
function  "4”  (Laft,  Right  :  SQL_Char) 
ratum  SQL_Char ; 

—  pragma  INLINE  ("4"); 


—  Logical  Oparations  — 

—  typa  X  typa  «=>  Boolaan_with_unknown  — 

—  tha  coc^jariaon  oparators  ratum  tha  boolaan  valua 

—  UNKNOWN  if  aithar  paramatar  is  null;  otharwisa, 
tha  coog>arison  is  dona  in  accordance  with 

ANSI  X3. 135-1986  para  5.11  ganaral  rule  5;  that  is, 
tha  shorter  of  tha  two  string  parameters  is 
affectively  padded  with  blanks  to  be  tha  langth  of 

—  tha  longer  string  and  a  standard  Ada  comparison  is 

—  than  made 

function  Equals  (Laft,  Right  :  SQL_Char )  return  Boolaan_with_Unknown; 

—  pragma  INLINE  (Equals); 

function  Not_Equals  (Laft,  Right  :  SQL_Char) 

ratum  Boolean_with  Unknown; 

—  pragma  INLINE  (Not_Equals ) ; 

function  "<"  (Laft,  Right  :  SQL_Char)  ratum  Boolean_with_Unknown; 

—  pragma  INLINE  ("<"); 

function  ">"  (Laft,  Right  :  SQL_Char)  ratum  Boolean_with_Unknown; 

—  pragma  INLINE  (”>”); 

function  "<*"  (Laft,  Right  :  SQL_Char )  return  Boolaan_with_Unknown ; 
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—  pragma  INLINE  ("<="); 

function  ">="  (Left,  Right  SQL_Char)  raturn  Boolean  with_Unknown; 

—  pragma  INLINE  (”>="); 

—  type  =>  boolean  — 

function  Ie_Null (Value  :  SQL_Char)  return  Boolean; 

—  pragma  INLINE  ( I «_N ul 1 ) ; 

function  Not_Null (Value  :  SQL_Char )  return  Boolean; 

—  pragma  INLINE  (Not_Null) ; 

—  These  functions  of  class  type  =>  boolean 

—  equate  UNKNOWN  with  FALSE.  That  is,  they  return  TRUE 

—  only  when  the  function  returns  TRUE.  UNKNOWN  and  FALSE 

—  are  mapped  to  FALSE . 

function  (Left,  Right  :  SQL_Char )  return  Boolean; 

—  pragma  INLINE  ("=”) : 

function  "<"  (Left,  Right  :  SQL_Char)  return  Boolean; 

—  pragma  INLINE  ("<") ; 

function  ">"  (Left,  Right  :  SQL_Char)  return  Boolean; 

—  pragma  INLINE  (”>"); 

function  "<="  (Left,  Right  :  SQL_Char)  return  Boolean; 

—  pragma  INLINE  ("<="); 

function  ”>="  (L«ft,  Right  .  SQL_Char)  raturn  Boolean; 

—  pragma  INLINE  (">=''); 


—  the  purpose  of  the  following  generic  is  to  generate 

conversion  functions  between  a  type  derived  from 
—  SQL_Char_Not_Null,  which  are  affectively  Ada 

strings  and  a  type  derived  from  SQL_Char,  which 
mimic  the  behaviour  of  SQL  strings. 

—  the  subprogram  formals  are  meant  to  default;  that  is, 

—  this  generic  should  be  instantiated  in  the  scope 
--  of  an  use  clause  for  SQb_Char_Pkg . 

generic 

type  With_Null_Type  is  limited  private ; 
type  Without_Null_Type  is  array  (positive  range  O) 
of  sql_standard . Char acter_type ; 
with  function  With_Null__Base  (Value:  SQL_Char_Not_Null) 
return  With_Null_Type  is  O; 
with  function  Without_Null_Base  (Value:  With_Nul l_Type ) 
return  SQL_Char_Not_Null  is  O; 

with  function  Without_Null_Unpadded_Base  (Value:  With_Null_Type) 
return  SQL_Char_Not  Null  is  O; 
package  SQL_Cbar_Ops  is 

function  With_Null  (Value  :  Without_Null_Type) 
return  With_Null_Type ; 

--  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Value  :  With_Null_Type) 
return  Without_Null_Type; 

—  pragma  INLINE  (Without_Null) ; 

function  Without_Null_Unpadded  (Value  :  With_Null_Type) 
return  Without_Null_Type ; 

—  pragma  INLINE  (Without_Null_Unpadded) ; 
end  SQL_Char_Ops ; 

private 

type  SQL_Char (Length  :  SQL_Char_Lengrth)  is  record 
Is_Null:  Boolean  :e  true; 

Unpadded_Length:  SQL_Unpadded_Length; 

Text:  SQL_Char_Not_Null (1  ..  Length); 
end  record; 
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end  SQL_C.har_Pkg; 


C.23  SQL_Char_Pkg  Body 

With  SQL  Exceptions  ; 

with  SQL_Standard; 

package  body  S QL_Char_P k g  is 

us«  SQL_S*~  snds rd .  Chsrsctsr_Sst ;  —  literals  to  be  interpreted  in 

—  DBMS  native  character  set 

Null_Value_Error  :  exception  renames  SQL  Exceptions .Mull  Value  Error; 

procedure  Assign  < 

Left  :  out  SQL_Char; 

Right  .  SQL_Char) 

is 

begin 

if  Right . ls_Null  then  Left.Is_Null  :=  True; 

else 

Left . Is_Null  :=  False; 

if  Left. Length  >=  Right . Onpadded_Length  then 

—  no  need  to  truncate;  blank  pad 

Left . Onpadded_Length  ; =  Right . Onpadded_Length; 

Left. Text  :=  Right .Text (1. .Right .Onpadded_Length) 
t  SQL_Char_Mot_Mull' 

(Right  .Unpadded_JLength  +  1  ..  Left.  length  —>  '  '); 

else 

—  truncate;  may  need  to  strip  blanks 

Lef t. Text (1. .Left. Length)  :=  Right . Text (1 . .Left .Length) ; 

—  remove  trailing  blanks  in  truncated  string 
declare 

unpadded_length_ctr  :  Natural  Left . length; 
begin 

for  i  in  reverse  1  . .  Left . length  loop 
exit  when  Right. Text (i)  /«  ' 

unpadded_langth__etr  :*  unpadded_length_ctr  -1; 
end  loop; 

Left .  unp adds d__l •  n g-th  :  e  unpadded_langth_ctr; 

end; 
end  if; 
end  if; 
end  Assign; 

function  With_Null_Base  (Value  :  SQL_Char_Not_Null) 
return  SQL_Char  is 

—  Calculate  the  Unpadded_Length  of  the  input  string 

—  without  the  trailing  blanks 

—  The  input  is  stored  in  the  output 

Onpadded_Langth_Ctr  :  Natural  :=  Value ' Length; 

subtype  Interned  is  SQL_Char_Not_Null  (1  ..  Value' Length) ;  —  allows  slices 
begin 

for  i  in  reverse  Value 'First  ..  Value 'Last 
loop 

exit  when  Value  (i)  /«=  '  '; 

Onpadded_Length_Ctr  =  0 np ad de d_Le ngth_Ct r  -1; 
end  loop; 

return (Length  =>  Value ' Length, 

Zs  Null  «=>  False, 
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Unpadded_Leng-th  *=>  Onpadded_Length  Ctr, 

Text  =>  Intermed (Value) ) ; 

•nd  With_Null_Baae ; 

function  Without_Nuli_Base (Valua  :  SQL_Char)  return  SQL_Char_Not_Null  is 
begin 

if  Value . Is_Null  then 

raise  Null_Value_Error ; 

else 

return  Value . Text ; 
end  if ; 

end  Without_Null_Base; 

function  Without_N ul l_Unpadded  Base (Value  :  SQL_Char ) 
return  SQL  C.har_Not  Mull  is 
begin 

if  Value . ls_Null  then 

raise  Null_Value_Error ; 

else 

return  (Value. Text (1 . .Value  .TJnpadded  Length) ) ; 
end  if; 

end  Without_Null_Onpadded_Baae; 

function  Nul l_SQL_Chax  return  SQL_Char  is 
Null_Holder  :  SQL_Char(l); 
begin 

return (Null_Holder) ;  —  relies  on  default  expression  for  Is_Null 
end  Null_SQL_Char; 

function  To_String  (Value  :  SQL_Char_Not_Null) 
return  String  is  separate; 

function  To_String  (Value  :  SQL_Char) 
return  String  is 
begin 

if  Value . Is_Hull  then 

raise  Null_Value_Error; 

else 

return  (To_String (Value . Text ) ) ; 
end  if; 

end  To_String; 

function  To_Onpadded_String  (Value  :  SQL_Char_Not_Null) 
return  String  is 
begin 

return  (To_String(Without_Null_Onpadded_Base (With_Null_Base (Value) ) ) ) ; 
end  To_Onpadded  String; 

function  To_Onpadded_String  (Value  :  SQL_Char ) 
return  String  is 
begin 

if  Value . Is_Null  then 

raise  Null_Value_Error ; 

else 

return  (To_String (Value .Text (1 . .Value . Onpadded_Length) )) ; 
end  if; 

end  To_Onpadded_String; 

function  To_SQL_Char_Mot_Mull  (Value  String) 
return  SQL_Char_Not_Mull  is  separate; 

function  To_SQL_Chax  (Value  ;  String) 
return  SQL  Char  is 
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allow*  alicaa 


—  Calculate  the  Dnpaddad  Length  of  the  input  string 

—  without  the  trailing  blanks 
--  The  input  is  stored  in  the  output 

Unpadded  Length  Ctr  :  Natural  :=  Value' Length; 
subtype  Interned  is  SQL_Char_Not_Null  (1  . .  Value'  Length) ;  — 
begin 

for  i  in  reverse  Value' First  ..  Value 'Last 
loop 

exit  when  Value (i)  /=  '  '; 

Unpadded  Length_Ctr  :=  Unpadded_Length_Ctr  -1; 
end  loop; 

return (Length  =>  Value 'Length, 

I»_Null  «=>  False, 

Unpadded_Length  =>  Unpadded  Length_Ctr, 

Text  =>  Interned (To_SQL_Char_Not_Null  (Value)  ))  ; 
end  To_SQL_Char ; 

function  Unpadded_Length  (Value  :  SQL_Char) 
return  SQL_Unpadded_L*ngth  is 
begin 

if  Value . Is_Null  then 

raise  Null_Value_Error ; 

else 

return  Value  .Unpadded__Length; 
end  if; 

end  Unpadded_L*ngth; 

f unction  Substring  (Value  :  SQL_Char; 

Start,  Length  :  SQL_Char_Length) 
return  SQL_Char  is 

begin 

if  Value. Is_Null  then 

return  Null_SQL_Char ; 

elsif  (Start  +  Length  -  1)  >  Value. Length  then 

—  no  need  to  check  Start  and  Length  here  to  see  that 

—  they  are  >  0 
--  the  rang*  constraints  on  the  subtype  SQL_Char_Length 

will  guarantee  that  *  run -time  check  is  made  of 

—  these  values  as  they  are  passed  into  "Substring" 
raise  constraint_error ; 

else 

return  With_Null_Ba»e (Value . Text (Start  ..  Start  +  Length  -  1) ) ; 
end  if; 

end  Substring; 

function  "6"  (Left,  Right  ;  SQL_Char) 
return  SQL_Ch*r  is 
begin 

if  Left . Is_Null  or  else  Right . Is_Null  then 
return  Null_SQL_Ch*r ; 

else 

return 

With_Null_B*s*  (Without_Null_Bas* (Left) 

&  Without_Null_B**e (Right) ) ; 

end  if; 
end  "i"; 

function  Equals  (Left,  Right:  SQL_Char)  return  Boolean_With_Un known  is 
begin 

if  L*ft.Is_Null  or  els*  Right . Is_Null  then 
return  U  nknown ; 

else 
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if  Left . Text ( 1 . . Left . Unpadded_I^ngth)  = 
Right .  Text  (1 .  .  Right .  Unpadded_Length) 
return  True; 

else 


return  Falsa; 

end  if; 
end  if; 
end  Equals ; 


then 


function  Not_Equals  (Left,  Right;  SQL_Char)  return  Boolean_With_Unknown  is 
begin 

if  Left . Is_Null  or  else  Right . Xs_Null  then 
return  Unknown ; 

else 


if  Left . Text (1 . .Left .Unpaddad_Langth)  /= 

Right . Text (1 . . Right . Unpadded_Length)  then 
return  True; 

else 


return  False; 

end  if ; 
end  if; 

end  Not_Equals; 


function  ">"  (Left,  Right:  SQL_Char)  return  Bool«an_With_Unknown  is 
begin 

if  Left.Xs_Null  or  else  Right . ls_Null  then 
return  Unknown ; 

else 

if  Left .Text (1 . .Left .Unpadded_Length)  > 

Right. Tt-rt  .  . Right . Unpadded_Length)  then 
return  True; 

else 

return  False ; 

end  if; 
end  if; 

end; 


function  ">«"  (Left,  Right:  SQL_Char)  return  Boolean_With_Unknown  is 
begin 

if  Left.Zs_Null  or  else  Right . Is_Null  then 
return  Unknown; 

else 

if  Left .  Text  (1 ..  Left  .Unpadded_Length)  >«= 

Right .Text (1 . .Right . Unpadded  Length)  then 
return  True; 

else 

return  False; 

end  if; 
end  if; 

end; 

function  "<"  (Left,  Right:  SQL_Char)  return  Boolean_With_Unknown  is 
begin 

if  Left.Xs_Hull  or  else  Right . Xs_Null  then 
return  Unknown; 

else 

if  Left . Text (1 .. Left .Unpadded_Length)  < 

Right .  Text  ( 1 .  .  Right .  Unpadded_I,ength)  then 
return  True; 

else 

return  False; 

end  if ; 
end  if ; 
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ond; 


function  "<»”  (Loft,  Right:  SQL_Chor)  ratum  Booloon_With_Onknown  10 
bogin 

if  Loft.Io_Null  or  oloo  Right . Is  Null  thon 
rotum  Unknown ; 

oloo 

if  Loft . Toxt (1 .. Loft . Cnpoddod_Longth)  <= 

Right . Toxt (1 . . Right . Unpoddod_Longth)  thon 
rotum  Truo; 

oloo 

rotum  Foloo; 

ond  if; 
ond  if; 

ond; 

function  Io  Null (Valuo  :  SQL  Char)  roturn  Booloon  io 
bogin 

rotum  Voluo  .  Io_Null  ; 
ond  Io_Null; 

function  Not  Null (Voluo  :  SQL  Chor)  rotum  Booloon  io 
bogin 

rotum  not  Voluo.  Io  Null; 
ond  Not_Null; 

function  (Loft,  Right:  SQL_Chor)  roturn  Booloon  io 

bogin 

if  Loft.Xo_Null  or  oloo  Right . Xo_Null  thon 
rotum  FALSE ; 

oloo 

if  Loft. Toxt(l. .Loft. Onpaddod_Longth)  = 

Right . Toxt ( 1 . . Right . Dnpoddod_Longth)  thon 
rotum  Truo; 

oloo 

rotum  Foloo; 

ond  if; 
ond  if; 
ond  ; 

function  "<"  (Loft,  Right:  SQL_Chox)  rotum  Booloon  io 
bogin 

if  Loft . Io_Null  or  oloo  Right . Io_Null  thon 
rotum  FALSE  ; 

oloo 

if  Loft . Toxt (1 . .Loft .Unpoddod_Longth)  < 

Right . Toxt (1 . . Right . Unpoddod_Longth)  thon 
rotum  Truo; 

oloo 

rotum  Foloo; 

ond  if; 
ond  if; 
ond  "<"; 

function  ">"  (Loft,  Right:  SQL_Chor)  rotum  Booloon  io 
bogin 

if  Loft . Io_Null  or  oloo  Right . Io_Null  thon 
rotum  FALSE ; 

oloo 

if  Loft .Toxt (1 .. Loft .Onpoddod_Longth)  > 

Right . Toxt (1 . . Right . Onpoddod_Longth)  thon 
rotum  Truo; 

oloo 
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return  Falsa ; 


and  if ; 
and  if ; 

and  ”>" ; 


function  "<="  (Laft,  Right:  SQL  Char)  return  Boolean  is 
begin 

if  Left.Is_Hull  or  else  Right . Is_Null  then 
return  FALSE; 

else 

if  Left . Text (1 . .Left .Dnpadded_Length)  <= 

Right . Text (1 . . Right . Unpadded_Length)  than 
return  True; 

else 


return  False; 

end  if; 
end  if; 
end  "<="; 


function  ">="  (Left,  Right:  SQL_Char)  return  Boolean  is 
begin 

if  Left  - Is_Null  or  else  Right . Is_Null  then 
return  FALSE ; 

else 

if  Left . Text ( 1 . . Left . Unpadded_Length)  >= 

Right . Text ( 1 . . Right . Onpadded_Length)  then 
return  True; 

else 

return  False; 

end  if; 
end  if; 
end  ">*" ; 


package  body  SQL_Char_Ops  is 

function  With_Null  (Value  :  Without_Null_Type) 
return  With_Null_Type  is 
begin 

return  With_Null_Base (SQL_Char_Not_Null (Value) ) ; 
end  WithJHull; 

function  Without  Hull  (Value  :  With_Null_Type) 
return  Without_Hull_Type  is 

begin 

return  With^ut_Null_Type ( 

SQL_Char_Hot_Null ' (Without_Null_Base (Value) ) ) ; 
end  Without_Null; 

function  Without_Null_Onpadded  (Value  :  With_Null_Type) 
return  Without_Null_Type  is 

begin 

return  Without_Hull_Type ( 

SQL_Char_Not_Hull '  (Without_Null_Onpadded_Base  (Value) ) ) ; 
end  Without_Hull  Dnpadded; 

end  SQL_Char_Ops ; 

end  SQL_Char_Pkg; 
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C.24  Subunit  To  String 

--  assuming  an  ascii  host  character  sat 

—  that  is  SQL_Standard . Character_Type  is  Standard . Character 
separata  (SQL_Cher_Pkg) 

function  To_String  (Value  :  SQL_Char_Not_Null) 
return  String  is 
begin 

return  (String (Value) ) ; 
end  To_String; 


C.25  Subunit  To  SQL  Char  Not  Null 


—  assuming  an  ascii  host  character  set 

—  that  is  SQL_Standard . Charactar_Type  is  Standard . Character 
separata  ( SQL_Cha  r_P  leg ) 

function  To_SQL_Char_N ot_N ul 1  (Value  :  String) 
return  SQL_Char_Not  Dull  is 
begin 

return  ( SQL_Char_Not_Nul 1 (Value) ) ; 
end  To  SQL  Char  Not  Null; 


C.2U  SQL_Enumeration_Pkg  Specification 

with  SQL _ Boole  an _ P  kg ;  use  SQL_Boolean  Pkg; 

with  SQL_Char_P kg ;  use  SQL_Char_Pkg; 
generic 

type  SQL_Enumeration_Not_Null  is  (O)  ; 
package  SQL_Enumeration_Pkg 

is 


-  Possibly  Null  Enumeration  - 

type  SQL_Bnumeration  is  limited  private; 

function  Null_SQL_Enumeration  return  SQL_Enumeration; 

—  pragma  INLINE  (Null_SQL_Enumaration) ; 

—  this  pair  of  functions  convert  between  the 

—  null-bearing  and  non-null -bearing  types, 
function  Without_Null (Value  :  in  SQL_Znumeration) 

return  SQL_Enumeration_Not_Null; 

—  pragma  INLINE  (Without_Null) ; 

—  With_Null  raises  Null_Value_Error  if  the  input 

value  is  null 

function  WithJNull  (Value  :  in  SQL  Enumeration  Not  Null) 
return  SQL_Enumaration; 

—  pragma  INLINE  (With_Null) ; 

procedure  Assign  ( 

Left  :  in  out  SQL_Enumeration;  Right  :  in  SQL_Rnumeration) ; 

—  pragma  INLINE  (Assign) ; 

—  Logical  Operations  — 

—  type  X  type  “>  Boolean_with_unknown  — 

—  these  functions  implement  three  valued  logic 

—  if  either  input  is  the  null  value,  the  functions 

return  the  truth  value  ON KNOWN;  otherwise  they 
perform  the  indicated  comparison. 
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function  Mot  Equals  (Left,  Right  :  SQL_Enumeration) 
rstum  Booloan  with  Unknown; 

—  pragma  INLINE  (Mot_Equals) ; 

function  "<"  (Loft,  Right  :  SQL_Enumeration)  raturn  Boolean_with_Unknown ; 
function  ”>"  (Loft,  Right  :  SQL_Enumaration)  roturn  Boolean_with_Onknown; 
function  "<*"  (Loft,  Right  :  SQL_Enumeration)  roturn  Boolean_with_Unknown; 
function  ">■"  (Loft,  Right  :  SQL_Enumoration)  roturn  Boolean with Unknown ; 

—  typo  ■>  booloan  — 

function  Is_Mull  (Valuo  :  SQL_Enumeration)  roturn  Booloan; 

—  pragma  IMLZME  (Is_Mull) ; 

function  Not_Null  (Value  :  SQL_Enumeration)  roturn  Booloan ; 

—  pragma  INLINE  (Not_Null) ; 

function  (Loft,  Right  :  SQL_Enumeration)  raturn  Booloan; 

—  pragma  INLINE  ("*”) ; 

function  "<"  (Loft,  Right  :  SQL_Enumoration)  roturn  Booloan; 

—  pragma  INLINE  ("<"); 

function  ">"  (Loft,  Right  :  SQL_Enumeration)  raturn  Booloan; 

—  pragma  INLINE  (">"); 

function  "<="  (Loft,  Right  :  SQL_Enumaration)  raturn  Booloan; 

—  pragma  INLINE  ("<«") ; 

function  ”>b"  (Loft,  Right  ;  SQL_Enumeration)  roturn  Booloan; 

—  pragma  INLINE  (">»") ; 


—  tho  following  six  functions  mimic  tho 

'Prod,  'Suae,  'Imago,  'Poo,  'Val,  and  'Valuo 
attributes  of  tho  SQL_Enuxnoration_Not_Null  typo,  passed 
in,  for  tho  associated  SQL_Enumeration  (null)  typo 

—  they  all  raise  tho  Null_Value_Error  excaption  if  a  null 

valuo  is  passed  in 

—  Prod  raises  tho  Constraint_Error  exception  if  tho  valuo 
passed  in  is  equal  to  SQL_Enumeration_Not_Null' Last 
—  Succ  raisas  tho  Constraint_Error  exception  if  tho  valuo 
passed  in  is  equal  to  SQL_Enumoration_Not_Null' First 
—  Val  raises  tho  Constraint_Error  exooption  if  tho  valuo  paosad 

in  is  not  in  tho  range  P' POS (P ' FIRST) . . P' POS (P' LAST)  for  typo  P 
—  Valuo  raises  tho  Constraint_Error  exception  if  tho  sequanoa  of 

—  characters  passed  in  does  not  havo  tho  syntax  of  an  onunoration 
litoral  for  tho  instantiated  enumeration  typo 

function  Prod  (Valuo  :  in  SQL_Enumeration)  raturn  SQL_Enumeration; 

—  pragma  INLINE  (Prod) ; 

function  Succ  (Valuo  :  in  SQL_Enumeration)  roturn  SQL_Enumoration; 

—  pragma  INLINE  (Succ) ; 

function  Poa  (Valuo  :  in  SQL  Enumeration)  roturn  Integer; 

—  pragma  INLINE  (Pos) ; 

function  Image  (Value  :  in  SQL  Enumeration)  return  SQL  Char; 
f unction  Image  (Value  :  in  SQL_Enumeration_Not_Null) 
return  SQL_Char_Not_Null ; 

—  pragma  INLINE  (Image) ; 

function  Val  (Value  :  in  Intoger)  return  SQL_Enumeration ; 

--  pragma  INLINE  (Val) ; 

function  Value  (Valuo  :  in  SQL  Char)  return  SQL_Enumeration; 
function  Value  (Value  :  in  SQL_Char_Not_Null) 
roturn  SQL_Enumeration_Not_Null; 

—  pragma  INLINE  (Value) ; 

private 

type  SQL_Enumeration  is  record 
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!•  Hull:  Boolean  : =  true; 

Value:  SQL_Enumeration_Not_Null; 
end  record; 

end  SQL  Enumeration _ Pkg; 


C.27  SQL_Enumeration_Pkg  Body 

With  SQL_Exceptiona ; 

package  body  SQL_Enumeration_Pkg 

la 

Null  Value  Error  :  exception  renames  SQL_Exceptions .Null_Value_Error; 

function  Null_SQL_Enumeration  return  SQL_Enumeration  is 
Null_Holder  :  SQL_Enumeration; 
begin 

return  Null_Holder; 
end  Hull  SQL  Enumeration; 

function  Without_Null (Value  :  in  SQL_Enumeration) 
return  SQL_Enumeration  Not  Null  is 
begin 

if  Value . Is_Null  then 

raise  Null_Value_Error ; 

else 

return  Value. Value; 
end  if; 

end  Without_Null ; 

function  With_Null (Value  :  in  SQL_Enumeration_Not_Null ) 
return  SQL_Enumeration  is 
begin 

return  (Is_Null  ■>  false, 

Value  «>  Value) ; 
end  With  Null; 

procedure  Assign  (left  :  in  out  SQL_Enume ration  ; 

Right  :  in  SQL  Enumeration)  is 

begin 

Left  : =  Right; 
end  Assign; 

function  Equals  (Left,  Right  :  SQL_Enumeration) 
return  8oolean_With  Unknown  is 
begin 

if  Left.Is_Null  or  else  Right . Is_Null  then 
return  Unknown ; 

elsif  Left. Value  =  Right. Value  then 
return  True; 

else 

return  False ; 
end  if; 
end  Equals ; 

function  Not_Equals  (Left,  Right  :  SQL_Enumeration) 
return  Boolean_With_Unknown  is 
begin 

if  Left.Zs_Null  or  else  Right . Is_Null  then 
return  Unknown; 
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alsif  La ft .Valua  /=  Right. Valua  than 
ratum  Trua; 

alaa 

ratum  Falsa; 
and  if; 

and  Not_Equala  ; 

function  "<"  (Laft,  Right  :  SQL_Enumaration) 
ratum  Boolaan_With_Unknown  ia 
bagin 

if  Laft. la  Null  or  alaa  Right . Is_Null  than 
ratum  Unknown; 

alsif  Laft.Valua  <  Right. Valua  than 
ratum  Trua; 

alaa 

ratum  Falsa; 
and  if; 
and  "<"; 

function  ">”  (Laft,  Right  :  SQL_Enum«r*tion) 
ratum  Boolaan_With_Onknown  is 
bagin 

if  Laft.Zs_Null  or  alaa  Right . Is_Null  than 
ratum  Unknown ; 

alsif  Laft.Valua  >  Right. Valua  than 
ratum  Trua; 

alsa 

ratum  Falsa; 
and  if; 
and  ">" ; 

function  "<="  (Laft,  Right  ;  SQL_Enumaration) 
ratum  Boolaan_With_Unknown  is 
bagin 

if  Laft . ls_Null  or  alsa  Right . Is_Null  than 
ratum  Unknown  ; 

alsif  Laft.Valua  <*=  Right. Valua  than 
ratum  Trua; 

alsa 

ratum  Falsa; 
and  if; 
and  "<«=”; 

function  ”>■"  (Laft,  Right  :  SQL_Enumaration) 
ratum  Boolaan_]Hith_Unknown  is 
bagin 

if  Laft.Is_Null  or  alsa  Right. Is  Null  than 
ratum  Unknown  ; 

alsif  Laft.Valua  >=  Right. Valua  than 
ratum  Trua; 

alsa 

ratum  Falsa; 
and  if; 
and  ">«="; 

function  Xs_Null  (Valua  :  SQL_Enumaration) 
ratum  Boolaan  is 
bagin 

ratum  Valua .  IsJNull ; 
and  Is_Null; 

function  Not_Null  (Valua  :  SQL_Bnumaration) 
ratum  Boolaan  is 
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begin 

return  not  Value . Is_Null; 
end  Not_Null; 

function  "="  (Left,  Right  :  SQL _ Enumer at ion ) 

return  Boolean  ia 
begin 

if  Lef  t .  Is_Null  or  elie  Right .  Is_Hull  then 
return  Falae; 

elsif  Left. Value  «=  Right. Value  then 
return  True; 

elee 

return  False; 
end  if; 

end 

function  "<”  (Left,  Right  :  SQL_Enumeration) 
return  Boolean  is 
begin 

if  Left.Is_Null  or  else  Right . Is_Null  then 
return  False; 

elsif  Left. Value  <  Right. Value  then 
return  True; 

else 

return  False ; 
end  if; 

end 

function  ">"  (Left,  Right  :  SQL_Enumeration) 
return  Boolean  is 
begin 

if  Left.IsJNull  or  else  Right . Ia_Null  then 
return  False; 

elsif  Left. Value  >  Right. Value  then 
return  True; 

else 

return  False; 
end  if; 

end 

function  " <= "  (Left,  Right  :  SQL_Enumeration) 
return  Boolean  is 
begin 

if  Left . I«_Null  or  else  Right . Is_Null  then 
return  False; 

elsif  Left. Value  <—  Right. Value  then 
return  True ; 

else 

return  False; 
end  if ; 
end  "<="; 

function  ">«="  (Left,  Right  :  S QL_Enuine ration) 
return  Boolean  is 
begin 

if  Left.Is_Null  or  else  Right . Is_Null  then 
return  False; 

elsif  Left. Value  >e  Right. Value  then 
return  True ; 

else 

return  False ; 
end  if; 

end 


CMU/SEI-89-TR-1 6 


function  Prod  (Valua  :  ir.  SQL_Enumaration) 
return  SQL_Enumaration  ia 
bagin 

if  Valua . Ia_Null  than 

ratum  Null_SQL_Enuraaration; 

alsa 

ratum  (With_Null (SQL_Enumaration_Not_Null ' Prad (Valua . Valua) ) ) ; 
and  if ; 
and  Prad; 

function  Succ  (Valua  :  in  SQL_Enumaration) 
ratum  SQL_Enumaration  ia 
bagin 

if  Valua . Ia_Null  than 

ratum  Null_SQL_Knumaration; 

alaa 

ratum  (With_Null (SQL_Enumaration_Not_Null ' Succ (Valua . Valua) ) ) ; 
and  if ; 
and  Succ ; 

function  Poa  (Valua  :  in  SQL_Enumaration)  ratum  Intagar  ia 
bagin 

if  Valua  .  Ia_Null  than 

raiaa  Null_Valua_Error  ; 

alaa 

ratum  SQL_Enumaration_Not_Null' Poa (Valua .Valua) ; 
and  if ; 
and  Poa; 

function  Imaga  (Valua  :  in  SQL_Enumaration_Not_Null) 
ratum  SQL_Char_Not_Null  ia 
bagin 

ratum  To_SQL_Char_Not_Null  ( 

SQL_Enumaration_Not_Null' Imaga (Valua) ) ; 

and  Imaga ; 

function  Imaga  (Valua  :  in  SQL_Enumaration) 
ratum  SQL_Chax  ia 
bagin 

if  Valua . Ia_Null  than 

raiaa  Null_Valua_Error ; 

alaa 

ratum  To_SQL_Cha r  ( SQL_Enuma rati on_N ot_N ul  1 '  Imaga  (Valua .  Valua)  )  ; 
and  if; 
and  Imaga ; 

function  Val  (Valua  :  in  Intagar)  ratum  SQL_Enumaration  ia 
bagin 

ratum  (With_Null  (SQL_Enumaration_Not_Null '  Val  (Valua)  )  )  ; 
and  V»l; 

function  Valua  (Valua  :  in  SQL_Char  Not_Null) 
ratum  SQL_Enumaration_Mot_Mull  ia 
bagin 

ratum  (SQL  Enumaration  Mot  Null ' Valua (To  String (Valua) )) ; 
and  Valua; 

function  Valua  (Valua  :  in  SQL  Char) 
ratum  SQL_Enumaration  ia 
bagin 

If  Ia_Null (Valua)  than 

ratum  Null  SQL  Enumaration; 

alaa 
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return  With_Null ( SQL_Enumaration_Not_Null ' Valua ( 
To_String ( Valua ) ) ) ; 


and  if; 
and  Valua; 


and  SQL  Enumaration_Pkg; 


C.28  SQL_Database_Error_Pkg  Specification 

packaga  SQL_Databaoa_Error_Pkg  ia 

—  Tba  following  procadura  muat  b«  praaant  in  ovary  varsion  of 
—  SQL_Databaoa_Error  Pkg .  It' a  purposa  ia  to  parform  atandard 

—  procaaaing  of  unaxpactad  axcaptional  conditiona .  It  ahould  not 

—  attampt  arror  racovar . 

procadura  Procaaa_Databaaa_Error; 
and  SQL_Databaaa_Error_Pkg; 


C.29  SQL_Database_Error_Pkg  Body 

with  Taxt_IO,  SQL_Communieationa_Pkg,  SQL_Baaa_Typaa_Pkg; 
uaa  Ta*t_IO,  SQL_Communicationa_Pkg,  SQL_Baaa_Typaa_Pkg; 
packaga  body  SQL_Databaaa_Error_Pkg  ia 

procadura  Procaaa_Databaaa_Error  ia 

bagin 


—  Procadura  ProoaaaJDatabaaa_Error  ia  callad  in  raaponaa 

to  an  unaxpactad  databaaa  axcaption  (an  arror  incidant) . 

Tha  procadura  may  ba  modifiad  par 
tha  naada  of  tha  Abatract  Intarfaca  davalopar 

—  Thia  ia  a  minimal  implamantation. 

Ca  -  a  daacriptiva  arror  maaaaga  from  tha  DBMS 
(through  tha  packaga  SQL_Cocnmunicationo_Pkg) 

—  and  diaplay  it  on  atandard  output. 

put_lina  (To_String ( SQL_Char_Mot_Mull (SQL_Databaaa_Error_Maaaaga) ) ) ; 
and  Procaaa  Databaaa  Error; 

m 

and  SQL_Databaaa_Error_Pkg; 


C.30  SQL_Date_Pkg  Specification 

with  SQL_Standard; 
with  Calandar;  uaa  Calandar; 
with  SQL_Boolaan_Pkg;  uaa  SQL_Boolaan_Pkg; 
with  SQL_Char_Pkg;  uaa  SQL_Char_Pkg ; 
packaga  SQL_Data_Pkg 
ia 

ty pa  praciaion  ia  ranga  0..10; 
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type  SQL_Datetime_Field  is  (year,  month,  day, 

hour,  minute,  second,  fraction')  ; 
type  SQL_Date_Not_Null  is  new  SQL_Char_Not_Nu.il ; 

type  SQL_Date (From  :  SQL_Datatime_Fiel& • 

To  :  SQL_Datetime_Field; 

Fraotional  :  precision)  is  limited  private; 

type  SQL_lnterval (From  :  SQL_Datetime_Field; 

Leading  :  precision; 

To  SQL  Datetime_Field; 

Fractional  :  precision)  is  limited  private; 

function  Null_SQL_Date  return  SQL_Date; 

—  pragma  INLINE  (Null_SQL_Date) ; 

function  Null_SQL_Interval  return  SQL_Interval ; 

—  pragma  INLINE  (Null_SQL_Interval) ; 

—  these  functions  return  the  not-null  portion  of  the  null-bearing  type 
function  Without_Null_Baae (Value  :  SQL_Date)  return  SQL_Date_Not_Null; 
function  Without_Null_Baae (Value  :  SQL_Interval)  return  SQL_Date_Not_Null ; 

—  pragma  INLINE  (Without_Null_Base) ; 

—  this  function  returns  an  object  of  the  standard . duration  type,  after 

converting  to  it  from  the  input  object  of  type  SQL_Interval 
function  To_Duration  (Value  :  SQL_Interval)  return  duration; 

—  pragma  INLINE  (To_Duration) ; 

—  this  function  returns  an  object  of  the  calendar . time  type,  after 

converting  to  it  from  the  input  object  of  type  SQL_Date 
function  To_Time  (Value  ;  SQL_Date)  return  time; 

--  pragma  INLINE  (To_Time)  ; 

these  procedures  parse  the  input  of  type  SQL_Date_Not_Null,  and  assign 
the  datetime  and  interval  field  values  to  the  objects  of  type 
SQL_Date  and  SQL_Interval ,  using  discriminants  that  it  determines  are 

—  the  correct  ones  for  the  object.  If  these  discriminants  differ  from 
the  ones  supplied  in  the  abstract  domain  for  the  object  when  it  was 

—  declared,  a  constraint_error  will  be  raised, 
procedure  Farse_and_Aasign_Bcse (Left :  in  out  SQL_Date; 

Right  :  SQL_Date_Not_Null) ; 

procedure  Parse_and_Assign_Base (Left :  in  out  SQL_Interval; 

Right  :SQL_Date_Not_Null) ; 

—  pragma  INLINE  ( Par se_and_As sign) ; 

—  this  function  accepts  input  of  type  standard. duration,  and 

returns  an  object  of  type  SQL_Interval  whose  not-null  portion 

—  has  the  correct  SQL  "interval''  value  specification  format, 

(FROM  «>  day,  LEADING  *>  2,  TO  =>  fraction,  FRACTIONAL  =>  3) 

function  To_SQL_Interval  (Value  :  duration)  return  SQL_Interval ; 

—  pragma  INLINE  (To_SQL_Interval) ; 

—  this  function  accepts  input  of  type  standard . time ,  and 

returns  an  object  of  type  SQL_Date  whose  not-null  portion 
has  the  correct  SQL  ” datetime "  value  specification  format 
function  To_SQL_Date  (Value  :  time)  return  SQL_Date; 

--  pragma  INLINE  (To_SQL_Date) ; 

—  the  assign  procedure  assigns  Right  to  Left 

procedure  Assign (Left  :  in  out  SQL_Date;  Right  :  SQL  Date) ; 
procedure  Assign (Left  :  in  out  SQL_Int  val;  Right  :  SQL_Interval) ; 

—  pragma  INLINE  (Assign) ; 

—  the  following  three  functions  implement  unary  "+",  "abs" 
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for  the  SQL_Interval  type 

function  "+" (Right  :  SQL_Interval)  return  SQL_Interval ; 
function  "-"(Right  :  SQL_Interval)  return  SQL_Interval ; 
function  "aba" (Right  :  SQL_Interval)  return  SQL_Interval ; 

—  pragma  INLINE  ("aba") ; 

—  the  following  functions  implement  three  valued 

—  arithmetic 

—  if  either  input  to  any  of  these  functions  is  null 

—  the  function  returns  the  null  value;  otherwise 

—  they  perform  the  indicated  operation 

—  these  functions  raise  no  exceptions 

function  "+" (Left,  Right  :  SQL  Interval)  return  SQL_Interval ; 
function  Plus (Left  :  SQL_Interval;  Right  :  SQL_Date)  return  SQL_Date; 
function  Plus (Left  :  SQL_Date;  Right  :  SQL_Interval)  return  SQL_Data; 

—  pragma  INLINE  ("+"); 

function  "-"(Left,  Right  :  SQL_Interval)  return  SQL_Interval ; 

function  Minus (Left,  Right  :  SQL_Date)  return  SQL_Interval; 

function  Minus (Left  :  SQL_Date;  Right  :  SQL_Interval)  return  SQL  Date; 

—  pragma  INLINE  ( " - " ) ; 

function  (Left  :  SQL_Interval ;  Right  :  integer)  return  SQL_Interval ; 

—  pragma  INLINE  ("*"); 

function  "/"(Left  :  SQL_Interval;  Right  :  integer)  return  SQL_Interval ; 

—  pragma  INLINE  ("/"); 

—  Logical  Operations  — 

--  type  X  type  *=>  Boolean_with_unknown  — 

—  these  functions  implement  three  valued  logic 

—  if  either  input  is  the  null  value,  the  functions 

return  the  truth  value  UNKNOWN;  otherwise  they 

—  perform  the  indicated  comparison. 

—  these  functions  raise  no  exceptions 

function  Equals  (Left,  Right  :  SQL_Date)  return  Boolean_with_Onknown; 
f unction  Equals  (Left,  Right  :  SQL_Interval)  return  Boolean_with_Onhnown ; 

—  pragma  INLINE  (Equals) ; 

function  Not_Equals  (Left,  Right  :  SQL_Date) 

return  Boolean_with_Dnknown; 
function  Not_Equals  (Left,  Right  :  SQL_Interval) 

return  Boolean_with_DnJcnown; 

—  pragma  INLINE  (Not_Equals) ; 

function  "<"  (Left,  Right  :  SQL_Date)  return  Boolean_with_Un)cnown ; 
function  (Left,  Right  :  SQL_Interval)  return  Boolean  with_Onknown; 

—  pragma  INLINE  ("<"); 

function  ">"  (Left,  Right  ;  SQL_Date)  return  Boolean_with_Onlcnown ; 
function  ”>"  (Left,  Right  :  SQL_Interval)  return  Boolean_with_Onknown; 

—  pragma  INLINE  (">"); 

function  "<="  (Left,  Right  :  SQL_Date)  return  Boolean_with_Onknown; 
function  "<="  (Left,  Right  SQL_Interval)  return  Boolean_with_Onknown ; 

—  pragma  INLINE  ("<="); 

function  ">="  (Left,  Right  :  SQL_Date)  return  Boolean_with_Unknown; 
function  ">="  (Left,  Right  :  SQL_Interval)  return  Boolean_with_Dnknown; 

—  pragma  INLINE  (">="); 

—  type  =>  boolean  — 

function  Is_Null (Value  :  SQL_Date)  return  Boolean; 
function  Is_Null (Value  :  SQL_Interval)  return  Boolean; 

—  pragma  INLINE  (Is_Null) ; 

function  Not_Null (Value  :  SQL_Date)  return  Boolean; 
function  Not_Null (Value  ;  SQL_Interval)  return  Boolean; 

—  pragma  INLINE  (Not_Null) ; 

function  Is_Year_Month (Value  SQL_Interval)  return  Boolean; 

—  pragma  INLINE (I a_Year_Month) ; 

function  Is_Day_Time (Value  :  SQL_Interval)  return  Boolean; 


CMU/SEI-89-TR-1 6 


243 


--  pragma  INLINE ( Ia_Day_Tima) ; 

function  Not  Yaar  Month (Valua  SQL_Intarv»l )  ratum  Boolaan; 

--  pragma  INLINE (Not_Yaar_Month) ; 

function  Not  Day_Tima (Valua  SQL_Intarval)  raturn  Boolaan; 

--  pragma  INLINE  (Not_Day_Tima) ; 

—  tha  procadura  Currant  raturna  tha  currant  ayatam  Datatima,  uaing 

tha  praciaion  of  tha  input  variabla 
procadura  Currant  (Valua  :  in  out  SQL  Data) ; 

—  pragma  INLINE (Currant) ; 

—  tha  procadura  Extand  raturna  tha  valua  of  tha  Right  input  objact  with 

tha  datatima  qualifiar  of  tha  Laft  objact,  if  a  valid  datatima 

—  valua  ia  ganaratad  by  tha  axtanaion  procaaa 
procadura  Extand  (Valua  :  in  out  SQL__Data) ; 

—  pragma  INLINE (Extand) ; 

--  thia  ganaric  ia  inatantiatad  onca  for  avary  aba tract 

SQL  Data  domain,  and  onca  for  avary  abatract  SQL_Intarval 
domain,  baaad  on  tha  typa  SQL  Data  Not_Null . 

—  tha  two  subprogram  formal  paramatara  art  maant  to 

daf ault  to  tha  programs  daclarad  abova . 

—  that  ia,  tha  packaga  should  ba  inatantiatad  in  tha 

acopa  of  a  uaa  clausa  for  SQL  Data_Pkg. 

—  tha  two  actvsl  typa  a  togathar  form  tha  abstract 

domain. 

—  tha  purpoaa  of  tha  ganaric  is  to  craata  functions 

which  convart  batwaan  tha  two  actual  typa a 

—  tha  bodias  of  thasa  subprograms  ara  calls  to 

subprograms  daclarad  abova  and  paaaad  as  dafaulta  to 
tha  ganaric. 

ganaric 

typa  With_Null_Typa  ia  limitad  privata; 
typa  Without_Null_Typa  is  array  (poaitiva  ranga  O) 
of  SQL_Standard . Charactar_typa ; 
with  procadura  Parsa_and_Assign  Basa 

(Laft  :  in  out  With_Null_Typa ;  Right  :  SQL_Data_Not_Null )  is  <>; 
with  function  Without_Null_Baaa (Valua  :  With_Null_Typa) 
ratum  SQL_Data_Not_Null  is  O; 
packaga  SQL_Data_Opa  is 

procadura  Parsa_and_Aasign  (Laft  :  With_Null_Typa; 

Right  :  Without_Null_Typa)  ; 

—  pragma  INLINE  (Parsa_and_Aasign) ; 
function  Without_Null  (Valua  :  With_I!ull_Typa ) 

ratum  Without_Null_typa ; 

—  pragma  INLINE  (Without_Null ) ; 
and  SQL_Data  Ops ; 

ganaric 

typa  With_Null_Data_Typa  is  limitad  privata ; 
typa  With_Null_Intarval_Typa  is  limitad  privata; 

with  function  Plus  (Laft  :  With_Null_Data_Typa ;  Right  :  SQL_Intarval ) 
raturn  With_Null_Data_Typa  is  <>; 

with  function  Plus  (Laft  :  SQL_Intarval;  Right  ;  With_Null_Data_Typa) 
raturn  With_Null_Data_Typa  ia  <> ; 

with  function  Minus  (Laft  :  With_Null_Data_Typa;  Right  :  SQL_Intarval) 
raturn  With_Null_Data_Typa  ia  <>; 
with  function  Minus  (Laft,  Right  :  With_Null_Data_Typa) 
ratum  SQL  Intarval  is  O; 
packaga  SQL_Data_Intarval_Ope  is 

function  "+"  (Laft  :  With_Null_Data_Typa ;  Right  :  With_Null_Intarval_Typa) 
ratum  With_Null_Data_Typa ; 

function  "+"  (Laft  :  With_Null_Intarval_Typa;  Right  :  With_Null_Data_'Typa) 
ratum  With_Null  Data_Typa; 
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function  (Laft  :  With_Null_Dat#_Typa;  Right  :  With_Null_Int#rv*l_Typa) 

rtturn  With_Null_Dat*_Typ* ; 
function  (Laft,  Right  :  With_Null_Dat*_Typa) 

rttum  With_Null_Int*rval_Typa; 
uid  SQL_Dat*_Int*rval_Opa; 

privat* 


typ*  SQI__yaax_nunibar 

is 

rang* 

1600. .9999 

typ* 

SQL  month  nuabar 

is 

rang# 

1. 

.12; 

typ* 

SQL  day  nuabar 

is 

rang# 

1. 

.31; 

typ* 

SQL  hour  nuabar 

is 

rang* 

0. 

.23; 

typ* 

SQL_minut*_nuab*x 

is 

rang* 

0. 

.59; 

typ* 

SQL  aacond  nuabar 

is 

rang* 

0. 

.59; 

typ*  SQL  f  raction_numb*r  ia  rang*  0  ..  (2**31)  -1  ; 

typa  SQL_intarval_numb*r  ia  rang*  -  (2**31)  ..  (2**31) -1; 

typa  SQL  Data (From  SQL_Datatim*_Fi*ld; 

To  SQL_Datatim*_Fi*ld; 

Fr actional  :  precision) 

ia  racord 

Ia_Null  :  Boolaan  trua; 

yaar  :  SQL  yaar  nuabar  ; 

month  SQL  month_numha  r ; 

day  :  SQL  day_nuab*r; 

hour  SQL  hour  nunbar ; 

minuta  :  SQL  m±nut*_numb*r ; 

aacond  SQL  aacond  nuabar; 

fraction  :  SQL_f  raction_numb*r ; 
and  racord; 

typ*  SQL_Int*rval (From  :  SQL_Dat*tio*_Fi*ld; 

Laading  ;  prmaxmioa; 

To  *  :  SQL_Datatim*_Fi*ld; 

Fractional  :  praciaion) 

ia  racord 

Ia_Null  :  boolaan  : *  Trua; 

Ia_T**r_Month  :  boolaan  :•  Trua; 

yaara  :  SQL_int*rval_nuob*r; 

montha  :  SQL_intarval_numb*r; 

day*  :  SQL_int*rval_numb*r; 

minutaa  :  SQL_int*rval  nuabar; 

aaoonda  :  SQL_int*rval_numb*r; 

fraction  :  SQL_intarval_numb*r ; 

and  racord ; 

and  SQL_Dat*_Pkg; 


C.31  INGRES_Date_Pkg  Specification 

with  SQL_Standard; 
with  SQL_Syatam;  ua*  SQL_Syat*m; 
with  Calandar;  uaa  Cal an da r; 
with  SQL_Bool*an  Pkg;  ua*  SQL_Bool*an_Pkg; 
with  SQL_Char_Pkg;  ua*  SQL_Cha r_Pkg ; 
packaga  INGRES_Dat*  Pkg 
ia 

typ*  IM<5RES_Dat*_Not_Mull  ia  naw  SQL_Char_Not_Null ; 
-  Poaaibly  Mull  Datatim*  - 
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type  INGRES_Date_Format  is  (Datetime,  Interval ,  Unknown); 
type  INGRES_Date (Format  INGRES_Date_Format  :=  Unknown) 
is  limited  private; 

function  Null_INGRES_Date  return  INGRES_Date; 

—  pregm*  INLINE  (Null_INGR2S_D«te) ; 

—  this  function  accepts  input  of  type  INGRES  Date  Not  Null,  and 

returns  an  object  whose  not-null  portion  is  the  input 
function  With_Null_Base (Value  :  INGRES_Date_Not_Null) 
return  INGRZS_Date; 

—  pragma  INLINE  (With_Null_Base) ; 

—  this  function  returns  the  not-null  portion  of  the  null-bearing  type 
function  Without_Null  Base (Value  :  INGRES_Date) 

return  INGRES_Date_Not_Null; 

—  pragma  INLINE  (Without_Nuil_Base) ; 

—  this  function  returns  the  not-null  portion  of  the  null-bearing  type 

this  function  differs  from  Without_Null_Base  in  that  the  output 
is  extended  to  include  all  fields, 
even  if  they  contain  a  value  of  zero 
--  INGRES  may  output  a  date  in  a  format 

—  that  is  unacceptable  as  INGRES  input . 

Therefore  this  function  extends  the  output  format  into  an  acceptable 
INGRES  input  format,  and  should  be  used  when  interacting  with  INGRES 
function  Without_Null_DBMS_Base (Value  :  INGRES_Date) 
return  INGRES_Date_Not_Null; 

—  pragma  INLINE  (Without_Null_DBMS_Base) ; 

—  this  function  raises  constraint_error  if  the  object  of  type 

INGRES__Dat »_Not_Null  is  not  in  the  correct  INCRES  "interval"  format 

—  of  the  INGRES  date  data  type 

function  To_Duration  (Value  :  INGRES_Date)  return  duration; 

—  pragma  INLINE  (To_Duration) ; 

—  this  function  raises  constraint  error  if  the  on^ject  of  type 

INGRES_Date_Not_Null  is  not  in  the  correct  INGRES  "datetime"  format 

—  of  the  INGRES  date  data  type 

function  lo_Tine  (Value  :  INGRES_Date)  return  tine; 

—  pragma  INLINE  (To_Time) ; 

—  this  function  accepts  input  of  type  standard . duration,  and 

returns  an  object  whose  not-null  portion  has  the  correct  INGRES 
"interval"  format  of  the  INGRES  date  data  type 
function  To_INGRES_Date  (Value  :  duration)  return  INGRES_Date; 

—  this  function  accepts  input  of  type  standard . time ,  and 

returns  an  object  whose  not-null  portion  has  the  INGRES  "datetime" 
format  of  the  INGRES  date  data  type 
function  To_INGRES_Date  (Value  :  time)  return  INGRES  Date; 

—  pragma  INLINE  (To_INGRES_Date) ; 

procedure  Assign (Left  :  in  out  INGRES_Date;  Right  •  INGRES_Date) ; 

—  pragma  INLINE  (Assign) ; 

--  the  following  three  functions  implement  unary  "+",  "abs" 

function  "+" (Right  :  INGR£S_Date)  return  INGRES_Date; 

function  "-"(Right  :  INGRES_Date)  return  INGRES_Date; 

function  "abs" (Right  :  INGRES_Date)  return  INGRES_Date : 

--  pragma  INLINE  ("abs"); 


246 


CMU/SEI-89-TR-1 6 


--  tha  following  function*  inplemant  three  valued 
arithmetic 

—  if  either  input  to  any  of  thaaa  function*  ia  null 

th*  function  ratum*  the  null  valua;  otherwise 
thay  parfons  tha  indicatad  oparation 

—  thaaa  function*  raiaa  no  exceptions 

function  "+" (Left,  Right  :  INGRES_D*te)  ratum  INGRES_D»te; 

—  pragma  INLINE  ("+")  ; 

function  "-"(Laft,  Right  :  INGRES_Date)  ratum  INGRES_Data; 

--  pragma  INLINE  ; 

—  Logical  Operation*  — 

—  typa  X  type  «>  Boolean_with_un)cnown  — 

—  tha* a  function*  implement  three  valued  logic 

—  if  either  input  i*  tha  null  valua,  tha  function* 

ratum  tha  truth  valua  UNKNOWN;  otherwise  thay 
perform  tha  indicatad  compariaon. 

—  thaaa  function*  raiaa  no  exception* 

function  Equal*  (Laft,  Right  :  INGRES_Date)  ratum  Boola*xi_»ith_Dnkno*n ; 
function  Not_Equal*  (Laft,  Right  :  INGRES_Date) 

ratum  Boolean_with_Unknown; 

function  "<"  (Laft,  Right  :  IN  GRES_D  at  a )  ratum  Boolt,an_with_UnJcnown; 
function  ">"  (Laft,  Right  INGRES_Date)  return  Boolean_with  Unknown; 
function  "<*"  (Laft,  Right  :  INGRES_Data)  ratum  Boolean  with_Onknown 
function  ">*"  (Laft,  Right  INGRES_Data)  ratum  Boolean_with  Unknown; 

—  hype  *>  boolean  — 

function  I*_Null (Valua  :  INGRES_Date)  ratum  Boolean; 

—  pragma  INLINE  (I*_Null) ; 

function  NotJNull (Valua  :  INGRES_Date)  return  Boolean • 

—  pragma  INLINE  (NotJNull) ; 

function  Equals  (Laft,  Right  :  INGRES_Date)  ratum  Boolean; 

—  pragma  INLINE  (Equals)  ; 

function  Not_Equal*  (Laft,  Right  :  INCRES_Date) 

return  Boolean ; 

--  pragma  INLINE  (Not_Equal*) ; 

function  "<"  (Laft,  Right  :  XNGRZS_Date)  ratum  Boolean; 

—  pragma  INLINE  ("<"); 

function  ">"  (Laft,  Right  :  INGRES _D ate)  ratum  Boolaac; 

—  pragma  INLINE  (">"); 

function  "<■"  (Laft,  Right  :  INGRES_Data)  ratum  Boolean; 

--  pragmn  INLINE  ("<■"); 

function  ">«"  (Laft,  Right  :  INGRES_Data)  ratum  Boolean; 

—  pragma  INLINE  (">—") ; 

—  this  generic  i*  instantiated  onoa  for  every  abatract 

domain  based  on  tha  typa  INGRES_Date_Not_Null . 

--  tha  two  subprogram  formal  parameter*  ara  meant  to 
default  to  tha  programs  declared  above. 

--  that  is,  tha  package  should  be  instantiated  in  tha 
scope  of  a  use  clausa  for  INGRES_Date_Pkg . 

—  tha  two  actual  types  together  form  the  abstract 

—  dootifi . 

—  th*  purpose  of  the  generic  i*  to  create  functions 

which  convert  between  the  two  actual  type* 

—  the  bodies  of  these  subprograms  ara  calls  to 

—  subprograms  declared  above  and  passed  a*  default*  to 
the  generic. 

generio 

type  With_Null_Typ*  is  limited  private; 
type  Without_Null_Type  ia  array  (positive  range  O ) 
of  SQL_Standard . Char*otar_Type ; 
with  function  With  Null  Base (Value  :  INGRES  Data  Not  Null) 
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rttum  With_Null_Typa  ia  <>; 

with  function  Without _ Null_Baaa (Vilu«  :  W_th_Null_Typa) 

ratum  INGR£S_Data  Not_Null  ia  <>: 

with  function  Without  Null_DBMS_Baaa (Valua  :  With_Null_Typa) 
r<tum  INGRES_Data_Not_Null  !■  <>; 
packaga  INGRES_Data_Opa  ia 

function  With  Null  (Valua  Without_Null  t ypa) 
ratucn  With_Null_Typa ; 

—  pragma  INLINE  (With_Null) ; 

function  Without_Null  (Valua  :  With_Null_Typa) 
ratum  Without  Null_typa; 

—  pragma  INLINE  (Witbout_Null) ; 

function  Without_Null_DBMS  (Valua  :  With_Null_Typa) 
ratum  Without_Null_typa ; 

—  pragma  INLINE  (Without_Null_DBMS) ; 
and  INCRES_Data_Opa ; 

privata 


typa 

INGRES_ye  ir  numbar 

ranga 

1582 . . 2 J82 

typa 

INGRES  month  numbar 

ia 

ranga 

1 . 

.  12; 

typa 

INGRES  day  numbar 

ia 

ranga 

1  . 

.31; 

typa 

INGRES  hour  numbar 

ia 

ranga 

0  . 

.23; 

typa 

INGRES  minuta  numbar 

la 

ranga 

0  . 

.59; 

typa 

INGRES  aacond  numbar 

xa 

ranga 

0. 

.59; 

typa  yaara_numbar  ia  ranga  -800.. 800; 

typa  month a _ numbar  ia  ranga  -(800*12) . . (800*12) ; 

typa  daya_numbar  la  ranga  - (292200) .. (292200) ;  --  800  •  36525 

typa  hour a_numha  r  ia  ranga  - (292200*24 )..  (292200*24 ) ; 

typa  mxnutaa_numbar  ia  ranga  - (292200*24 *60) .. (292200*24 *60) ; 

typa  aaconda_numbar  ia  ranga  - (2**31) . . (2**31) -1 ; 

typa  INGRES_Data (Format  :  INGRES_Data  Format  : "  Unknown)  ia  racord 
Ia_Null:  Boo la an  ;a  trua ; 
caaa  Format  ia 

whan  Datat.ima  *> 

yaar  INCRES_yaar  numbar ; 

month  :  INCRSS_montb_nuabar ; 
day  :  INGRES_day_numbar ; 
hour  INGRXS_hour  nrnbar; 

oinuta  .  INGRES_minuta_numbar ; 
aaoond  ;  INGRES  aacond  numbar; 
whan  Intarval  ■> 

yaar a  ;  yaar  a  numbar ; 
montha  ;  montha  numbar; 
daya  ;  daya_numbar; 
hour a  :  hour  a  numbar ; 
minutaa  :  unutaa  numbar  ; 
aaconda  aaconda  numbar ; 
whan  Unknown  => 
null; 
and  caaa ; 
and  racord; 

and  INGRES_Data_Pkg; 
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